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Abstract 

Welcome to the Ubuntu Server Guidel It contains information on how to install and configure various server 
applications on your Ubuntu system to fit your needs. It is a step-by-step, task-oriented guide for configuring 
and customizing your system. 
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of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE AS DESCRIBED IN THE DISCLAIMER. 
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Chapter 1. Introduction 



Welcome to the Ubuntu Server Guidel 

Here you can find information on how to install and configure various server applications. It is a step- 
by-step, task-oriented guide for configuring and customizing your system. 

This guide assumes you have a basic understanding of your Ubuntu system. Some installation details 
are covered in Chapter 2, Installation [p. 3], but if you need detailed instructions installing 
Ubuntu please refer to the Ubuntu Installation Guide 1 . 

A HTML version of the manual is available online at the Ubuntu Documentation website 2 . 



https://help.ubuntu.com/14.04/installation-guide/ 
https://help.ubuntu.com 
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Introduction 



1. Support 

There are a couple of different ways that Ubuntu Server Edition is supported, commercial support 
and community support. The main commercial support (and development funding) is available from 
Canonical Ltd. They supply reasonably priced support contracts on a per desktop or per server basis. 
For more information see the Canonical Services 3 page. 

Community support is also provided by dedicated individuals, and companies, that wish to make 
Ubuntu the best distribution possible. Support is provided through multiple mailing lists, IRC 
channels, forums, blogs, wikis, etc. The large amount of information available can be overwhelming, 
but a good search engine query can usually provide an answer to your questions. See the Ubuntu 
Support 4 page for more information. 



http://www.canonical.com/services/support 
http ://www .ubuntu .com/ support 
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Chapter 2. Installation 

This chapter provides a quick overview of installing Ubuntu 14.04 LTS Server Edition. For more 
detailed instructions, please refer to the Ubuntu Installation Guide 1 . 



https://help.ubuntu.com/14.04/installation-guide/ 
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1. Preparing to Install 

This section explains various aspects to consider before starting the installation. 

1.1. System Requirements 

Ubuntu 14.04 LTS Server Edition supports three (3) major architectures: Intel x86, AMD64 and 
ARM. The table below lists recommended hardware specifications. Depending on your needs, you 
might manage with less than this. However, most users risk being frustrated if they ignore these 
suggestions. 



Table 2.1. Recommended Minimum Requirements 



Install Type 


CPU 


RAM 


Hard Drive Space 


Base System 


All Tasks Installed 


Server (Standard) 


1 gigahertz 


512 megabytes 


1 gigabyte 


1 .75 gigabytes 


Server (Minimal) 


300 megahertz 


192 megabytes 


700 megabytes 


1 .4 gigabytes 



The Server Edition provides a common base for all sorts of server applications. It is a minimalist 
design providing a platform for the desired services, such as file/print services, web hosting, email 
hosting, etc. 

1.2. Server and Desktop Differences 



There are a few differences between the Ubuntu Server Edition and the Ubuntu Desktop Edition. It 
should be noted that both editions use the same apt repositories, making it just as easy to install a 
server application on the Desktop Edition as it is on the Server Edition. 

The differences between the two editions are the lack of an X window environment in the Server 
Edition and the installation process. 



1.2.1. Kernel Differences: 

Ubuntu version 10.10 and prior, actually had different kernels for the server and desktop editions. 
Ubuntu no longer has separate -server and -generic kernel flavors. These have been merged into a 
single -generic kernel flavor to help reduce the maintenance burden over the life of the release. 

When running a 64-bit version of Ubuntu on 64-bit processors you are not limited by 
memory addressing space. 

To see all kernel configuration options you can look through /boot/conf ig-3 . 13 . o-server. Also, 
Linux Kernel in a Nutshell 2 is a great resource on the options available. 

2 

http ://www .kroah .com/lkn/ 
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1.3. Backing Up 

• Before installing Ubuntu Server Edition you should make sure all data on the system is backed up. 
See Chapter 19, Backups [p. 299] for backup options. 

If this is not the first time an operating system has been installed on your computer, it is likely you 
will need to re -partition your disk to make room for Ubuntu. 

Any time you partition your disk, you should be prepared to lose everything on the disk should you 
make a mistake or something goes wrong during partitioning. The programs used in installation are 
quite reliable, most have seen years of use, but they also perform destructive actions. 
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2. Installing from CD 

The basic steps to install Ubuntu Server Edition from CD are the same as those for installing any 
operating system from CD. Unlike the Desktop Edition, the Server Edition does not include a 
graphical installation program. The Server Edition uses a console menu based process instead. 

• First, download and burn the appropriate ISO file from the Ubuntu web site 3 . 

• Boot the system from the CD-ROM drive. 

• At the boot prompt you will be asked to select a language. 

• From the main boot menu there are some additional options to install Ubuntu Server Edition. You 
can install a basic Ubuntu Server, check the CD-ROM for defects, check the system's RAM, boot 
from first hard disk, or rescue a broken system. The rest of this section will cover the basic Ubuntu 
Server install. 

• The installer asks for which language it should use. Afterwards, you are asked to select your 
location. 

• Next, the installation process begins by asking for your keyboard layout. You can ask the installer 
to attempt auto-detecting it, or you can select it manually from a list. 

• The installer then discovers your hardware configuration, and configures the network settings using 
DHCP. If you do not wish to use DHCP at the next screen choose "Go Back" , and you have the 
option to "Configure the network manually". 

• Next, the installer asks for the system's hostname. 

• A new user is set up; this user will have root access through the sudo utility. 

• After the user settings have been completed, you will be asked to encrypt your home directory. 

• Next, the installer asks for the system's Time Zone. 

• You can then choose from several options to configure the hard drive layout. Afterwards you 
are asked for which disk to install to. You may get confirmation prompts before rewriting the 
partition table or setting up LVM depending on disk layout. If you choose LVM, you will be 
asked for the size of the root logical volume. For advanced disk options see Section 4, "Advanced 
Installation" [p. 10]. 

• The Ubuntu base system is then installed. 

• The next step in the installation process is to decide how you want to update the system. There are 
three options: 

• No automatic updates: this requires an administrator to log into the machine and manually install 
updates. 

• Install security updates automatically: this will install the unattended-upgrades package, which 
will install security updates without the intervention of an administrator. For more details see 
Section 5, "Automatic Updates" [p. 27]. 

3 

http://www.ubuntu.com/download/server/download 
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• Manage the system with Landscape: Landscape is a paid service provided by Canonical to help 
manage your Ubuntu machines. See the Landscape 4 site for details. 

• You now have the option to install, or not install, several package tasks. See Section 2.1, "Package 
Tasks" [p. 77 for details. Also, there is an option to launch aptitude to choose specific 
packages to install. For more information see Section 4, "Aptitude" [p. 25]. 

• Finally, the last step before rebooting is to set the clock to UTC. 

If at any point during installation you are not satisfied by the default setting, use the "Go 
Back" function at any prompt to be brought to a detailed installation menu that will allow 
you to modify the default settings. 

At some point during the installation process you may want to read the help screen provided by the 
installation system. To do this, press Fl . 

Once again, for detailed instructions see the Ubuntu Installation Guide 5 . 

2.1. Package Tasks 

During the Server Edition installation you have the option of installing additional packages from the 
CD. The packages are grouped by the type of service they provide. 
DNS server: Selects the BIND DNS server and its documentation. 
LAMP server: Selects a ready-made Linux/ Apache/MySQL/PHP server. 

Mail server: This task selects a variety of packages useful for a general purpose mail server system. 
OpenSSH server: Selects packages needed for an OpenSSH server. 

PostgreSQL database: This task selects client and server packages for the PostgreSQL database. 
Print server: This task sets up your system to be a print server. 

Samba File server: This task sets up your system to be a Samba file server, which is especially 
suitable in networks with both Windows and Linux systems. 

Tomcat Java server: Installs Apache Tomcat and needed dependencies. 

Virtual Machine host: Includes packages needed to run KVM virtual machines. 

Manually select packages: Executes aptitude allowing you to individually select packages. 

Installing the package groups is accomplished using the tasksel utility. One of the important 
differences between Ubuntu (or Debian) and other GNU/Linux distribution is that, when installed, a 
package is also configured to reasonable defaults, eventually prompting you for additional required 
information. Likewise, when installing a task, the packages are not only installed, but also configured 
to provided a fully integrated service. 

Once the installation process has finished you can view a list of available tasks by entering the 
following from a terminal prompt: 



^ http://www.canonical.com/projects/landscape 
^ https ://help .ubuntu .com/ 14 .04/installation-guide/ 
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tasksel --list-tasks 

l%— I The output will list tasks from other Ubuntu based distributions such as Kubuntu and 

Edubuntu. Note that you can also invoke the tasksel command by itself, which will bring up 
a menu of the different tasks available. 

You can view a list of which packages are installed with each task using the —task-packages option. 
For example, to list the packages installed with the DNS Server task enter the following: 

tasksel — task-packages dns-server 

The output of the command should list: 

bind9-doc 

bind9utils 

bind9 

If you did not install one of the tasks during the installation process, but for example you decide to 
make your new LAMP server a DNS server as well, simply insert the installation CD and from a 
terminal: 

sudo tasksel Install dns-server 
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3. Upgrading 

There are several ways to upgrade from one Ubuntu release to another. This section gives an overview 
of the recommended upgrade method. 

3.1. do-release-upgrade 

The recommended way to upgrade a Server Edition installation is to use the do-release-upgrade 
utility. Part of the update-manager-core package, it does not have any graphical dependencies and is 
installed by default. 

Debian based systems can also be upgraded by using apt-get dist-upgrade. However, using do- 
release-upgrade is recommended because it has the ability to handle system configuration changes 
sometimes needed between releases. 

To upgrade to a newer release, from a terminal prompt enter: 
do-release-upgrade 

It is also possible to use do-release-upgrade to upgrade to a development version of Ubuntu. To 
accomplish this use the -d switch: 

do-release-upgrade -d 




Upgrading to a development release is not recommended for production environments. 
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4. Advanced Installation 



4.1. Software RAID 



Redundant Array of Independent Disks "RAID" is a method of using multiple disks to provide 
different balances of increasing data reliability and/or increasing input/output performance, depending 
on the RAID level being used. RAID is implemented in either software (where the operating system 
knows about both drives and actively maintains both of them) or hardware (where a special controller 
makes the OS think there's only one drive and maintains the drives 'invisibly'). 

The RAID software included with current versions of Linux (and Ubuntu) is based on the 'mdadm' 
driver and works very well, better even than many so-called 'hardware' RAID controllers. This section 
will guide you through installing Ubuntu Server Edition using two RAID1 partitions on two physical 
hard drives, one for / and another for swap. 

4.1.1. Partitioning 

Follow the installation steps until you get to the Partition disks step, then: 

1 . Select Manual as the partition method. 

2. Select the first hard drive, and agree to "Create a new empty partition table on this device?". 

Repeat this step for each drive you wish to be part of the RAID array. 

3. Select the "FREE SPACE" on the first drive then select "Create a new partition". 

4. Next, select the Size of the partition. This partition will be the swap partition, and a general 
rule for swap size is twice that of RAM. Enter the partition size, then choose Primary, then 
Beginning. 



5. Select the "Use as:" line at the top. By default this is "Ext4 journaling file system", change that to 
"physical volume for RAID" then "Done setting up partition". 

6. For the / partition once again select "Free Space" on the first drive then "Create a new partition". 

7. Use the rest of the free space on the drive and choose Continue, then Primary. 

8. As with the swap partition, select the "Use as:" line at the top, changing it to "physical volume 
for RAID". Also select the "Bootable flag:" line to change the value to "on". Then choose "Done 
setting up partition". 

9. Repeat steps three through eight for the other disk and partitions. 
4.1.2. RAID Configuration 

With the partitions setup the arrays are ready to be configured: 




A swap partition size of twice the available RAM capacity may not always be 
desirable, especially on systems with large amounts of RAM. Calculating the swap 
partition size for servers is highly dependent on how the system is going to be used. 
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1. Back in the main "Partition Disks" page, select "Configure Software RAID" at the top. 

2. Select "yes" to write the changes to disk. 

3. Choose "Create MD device" . 

4. For this example, select "RAID1 ", but if you are using a different setup choose the appropriate 
type (RAIDO RAID1 RAID5). 




In order to use RAID5 you need at least three drives. Using RAIDO or RAID1 only two 
drives are required. 



5. Enter the number of active devices "2", or the amount of hard drives you have, for the array. 
Then select "Continue" . 

6. Next, enter the number of spare devices "0" by default, then choose "Continue". 

7. Choose which partitions to use. Generally they will be sdal, sdbl, sdcl, etc. The numbers will 
usually match and the different letters correspond to different hard drives. 

For the swap partition choose sdal and sdbl. Select "Continue" to go to the next step. 

8. Repeat steps three through seven for the / partition choosing sda2 and sdb2. 

9. Once done select "Finish". 

4.1.3. Formatting 

There should now be a list of hard drives and RAID devices. The next step is to format and set the 
mount point for the RAID devices. Treat the RAID device as a local hard drive, format and mount 
accordingly. 

1 . Select "#i " under the "RAID1 device #0" partition. 

2. Choose "Use as:". Then select "swap area", then "Done setting up partition". 

3. Next, select "#i " under the "RAID1 device #1 " partition. 

4. Choose "Use as:". Then select "Ext4 journaling file system". 

5. Then select the "Mount point" and choose "/ - the root file system". Change any of the other 
options as appropriate, then select "Done setting up partition". 

6. Finally, select "Finish partitioning and write changes to disk". 

If you choose to place the root partition on a RAID array, the installer will then ask if you would like 
to boot in a degraded state . See Section 4.1.4, "Degraded RAID " [p. 11] for further details . 

The installation process will then continue normally. 

4.1 .4. Degraded RAID 

At some point in the life of the computer a disk failure event may occur. When this happens, using 
Software RAID, the operating system will place the array into what is known as a degraded state. 
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If the array has become degraded, due to the chance of data corruption, by default Ubuntu Server 
Edition will boot to initramfs after thirty seconds. Once the initramfs has booted there is a fifteen 
second prompt giving you the option to go ahead and boot the system, or attempt manual recover. 
Booting to the initramfs prompt may or may not be the desired behavior, especially if the machine is 
in a remote location. Booting to a degraded array can be configured several ways: 

• The dpkg-reconfigure utility can be used to configure the default behavior, and during the process 
you will be queried about additional settings related to the array. Such as monitoring, email alerts, 
etc. To reconfigure mdadm enter the following: 



sudo dpkg-reconfigure mdadm 

• The dpkg-reconfigure mdadm process will change the /etc/initramf s-toois/conf . d/mdadm 
configuration file. The file has the advantage of being able to pre-configure the system's behavior, 
and can also be manually edited: 



BOOT DEGRADED=true 



The configuration file can be overridden by using a Kernel argument. 



• Using a Kernel argument will allow the system to boot to a degraded array as well: 

• When the server is booting press Shift to open the Grub menu. 

• Press e to edit your kernel command options. 

• Press the down arrow to highlight the kernel line. 

• Add "bootdegraded=true" (without the quotes) to the end of the line. 

• Press Ctrl+x to boot the system. 

Once the system has booted you can either repair the array see Section 4.1.5, "RAID 
Maintenance" [p. 12] for details, or copy important data to another machine due to major 
hardware failure. 

4.1.5. RAID Maintenance 



The mdadm utility can be used to view the status of an array, add disks to an array, remove disks, etc: 
• To view the status of an array, from a terminal prompt enter: 



sudo mdadm -D /dev/mdO 



The -D tells mdadm to display detailed information about the /dev/mdO device. Replace /dev/mdO 
with the appropriate RAID device. 

• To view the status of a disk in an array: 



sudo mdadm -E /dev/sdal 
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The output if very similar to the mdadm -D command, adjust /dev/sdai for each disk. 

• If a disk fails and needs to be removed from an array enter: 

sudo mdadm — remove /dev/mdO /dev/sdal 

Change /dev/mdO and /dev/sdal to the appropriate RAID device and disk. 

• Similarly, to add a new disk: 

sudo mdadm — add /dev/mdO /dev/sdal 

Sometimes a disk can change to a faulty state even though there is nothing physically wrong with 
the drive. It is usually worthwhile to remove the drive from the array then re-add it. This will cause 
the drive to re- sync with the array. If the drive will not sync with the array, it is a good indication of 
hardware failure. 

The /proc/mdstat file also contains useful information about the system's RAID devices: 
cat /proc/mdstat 

Personalities : [linear] [multipath] [raidO] [raidl] [raid6] [raid5] [raid4] [raidlO] 
mdO : active raidl sdal[0] sdbl[l] 
10016384 blocks [2/2] [UU] 

unused devices: <none> 

The following command is great for watching the status of a syncing drive: 



watch -nl cat /proc/mdstat 

Press Ctrl+c to stop the watch command. 

If you do need to replace a faulty drive, after the drive has been replaced and synced, grub will need 
to be installed. To install grub on the new drive, enter the following: 



sudo grub-install /dev/mdO 

Replace /dev/mdO with the appropriate array device name. 
4.1.6. Resources 



The topic of RAID arrays is a complex one due to the plethora of ways RAID can be configured. 
Please see the following links for more information: 

• Ubuntu Wiki Articles on RAID 6 . 



https://help.ubuntu.eom/community/Installation#raid 
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• Software RAID HOWTO 1 

• Managing RAID on Linux & 

4.2. Logical Volume Manager (LVM) 

Logical Volume Manger, or LVM, allows administrators to create logical volumes out of one or 
multiple physical hard disks. LVM volumes can be created on both software RAID partitions and 
standard partitions residing on a single disk. Volumes can also be extended, giving greater flexibility 
to systems as requirements change. 

4.2.1. Overview 

A side effect of LVM's power and flexibility is a greater degree of complication. Before diving into 
the LVM installation process, it is best to get familiar with some terms. 

• Physical Volume (PV): physical hard disk, disk partition or software RAID partition formatted as 
LVM PV. 

• Volume Group (VG): is made from one or more physical volumes. A VG can can be extended by 
adding more PVs. A VG is like a virtual disk drive, from which one or more logical volumes are 
carved. 

• Logical Volume (LV): is similar to a partition in a non-LVM system. A LV is formatted with the 
desired file system (EXT3, XFS, JFS, etc), it is then available for mounting and data storage. 

4.2.2. Installation 

As an example this section covers installing Ubuntu Server Edition with /srv mounted on a LVM 
volume. During the initial install only one Physical Volume (PV) will be part of the Volume Group 
(VG). Another PV will be added after install to demonstrate how a VG can be extended. 

There are several installation options for LVM, "Guided - use the entire disk and setup LVM n which 
will also allow you to assign a portion of the available space to LVM, "Guided - use entire and setup 
encrypted LVM", or Manually setup the partitions and configure LVM. At this time the only way to 
configure a system with both LVM and standard partitions, during installation, is to use the Manual 
approach. 

1 . Follow the installation steps until you get to the Partition disks step, then: 

2. At the "Partition Disks screen choose "Manual". 

3. Select the hard disk and on the next screen choose "yes" to "Create a new empty partition table 
on this device". 

4. Next, create standard /boot, swap, and / partitions with whichever filesystem you prefer. 

5. For the LVM I srv, create a new Logical partition. Then change "Use as" to "physical volume for 
LVM" then "Done setting up the partition". 



http://www.faqs.org/docs/Linux-HOWTO/Software-RAID-HOWTO.html 
http://oreilly.com/catalog/9781565927308/ 
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6. Now select "Configure the Logical Volume Manager" at the top, and choose "Yes" to write the 
changes to disk. 

7. For the "LVM configuration action" on the next screen, choose "Create volume group". Enter a 
name for the VG such as vgOl, or something more descriptive. After entering a name, select the 
partition configured for LVM, and choose "Continue" . 

8. Back at the "LVM configuration action" screen, select "Create logical volume". Select the 
newly created volume group, and enter a name for the new LV, for example srv since that is the 
intended mount point. Then choose a size, which may be the full partition because it can always 
be extended later. Choose "Finish" and you should be back at the main "Partition Disks" screen. 

9. Now add a filesystem to the new LVM. Select the partition under "LVM VG vgOl, LV srv ", or 
whatever name you have chosen, the choose Use as. Setup a file system as normal selecting /srv 
as the mount point. Once done, select "Done setting up the partition". 

10. Finally, select "Finish partitioning and write changes to disk". Then confirm the changes and 
continue with the rest of the installation. 

There are some useful utilities to view information about LVM: 

• pvdisplay: shows information about Physical Volumes. 

• vgdisplay: shows information about Volume Groups. 

• Ivdisplay: shows information about Logical Volumes. 

4.2.3. Extending Volume Groups 

Continuing with srv as an LVM volume example, this section covers adding a second hard disk, 
creating a Physical Volume (PV), adding it to the volume group (VG), extending the logical volume 
srv and finally extending the filesystem. This example assumes a second hard disk has been added to 
the system. In this example, this hard disk will be named /dev/sdb and we will use the entire disk as a 
physical volume (you could choose to create partitions and use them as different physical volumes) 




Make sure you don't already have an existing /dev/sdb before issuing the commands below. 
You could lose some data if you issue those commands on a non-empty disk. 



1 . First, create the physical volume, in a terminal execute: 

sudo pvcreate /dev/ sdb 

2. Now extend the Volume Group (VG): 

sudo vgextend vgOl /dev/sdb 

3. Use vgdisplay to find out the free physical extents - Free PE / size (the size you can allocate). We 
will assume a free size of 5 1 1 PE (equivalent to 2GB with a PE size of 4MB) and we will use the 
whole free space available. Use your own PE and/or free space. 
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The Logical Volume (LV) can now be extended by different methods, we will only see how to 
use the PE to extend the LV: 



sudo lvextend /dev/vgOl/srv -1 +511 

The -/ option allows the LV to be extended using PE. The -L option allows the LV to be 
extended using Meg, Gig, Tera, etc bytes. 

4. Even though you are supposed to be able to expand an ext3 or ext4 filesystem without 

unmounting it first, it may be a good practice to unmount it anyway and check the filesystem, so 
that you don't mess up the day you want to reduce a logical volume (in that case unmounting first 
is compulsory). 

The following commands are for an EXT3 or EXT4 filesystem. If you are using another 
filesystem there may be other utilities available. 



sudo umount /srv 

sudo e2fsck -f /dev/vgOl/srv 

The -/option of e2fsck forces checking even if the system seems clean. 
5. Finally, resize the filesystem: 



sudo resize2fs /dev/vgOl/srv 

6. Now mount the partition and check its size. 



mount /dev/vgOl/srv /srv && df -h /srv 

4.2.4. Resources 

• See the Ubuntu Wiki LVM Articles 9 . 

• See the LVM HOWTO 10 for more information. 

• Another good article is Managing Disk Space with LVM U on O'Reilly's linuxdevcenter.com site. 

• For more information on fdisk see the j disk man page 12 . 



https://help.ubuntu.eom/community/Installation#lvm 
3 http://tldp.org/HOWTO/LVM-HOWTO/index.html 

' http://www.linuxdevcenter.eom/pub/a/linux/2006/04/27/managing-disk-space-with-lvm.html 
" http://manpages.ubuntu.eom/manpages/trusty/en/man8/fdisk.8.html 
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5. Kernel Crash Dump 

5.1. Introduction 

A Kernel Crash Dump refers to a portion of the contents of volatile memory (RAM) that is copied 
to disk whenever the execution of the kernel is disrupted. The following events can cause a kernel 
disruption : 

• Kernel Panic 

• Non Maskable Interrupts (NMI) 

• Machine Check Exceptions (MCE) 

• Hardware failure 

• Manual intervention 

For some of those events (panic, NMI) the kernel will react automatically and trigger the crash dump 
mechanism through kexec. In other situations a manual intervention is required in order to capture the 
memory. Whenever one of the above events occurs, it is important to find out the root cause in order 
to prevent it from happening again. The cause can be determined by inspecting the copied memory 
contents. 

5.2. Kernel Crash Dump Mechanism 

When a kernel panic occurs, the kernel relies on the kexec mechanism to quickly reboot a new 
instance of the kernel in a pre -reserved section of memory that had been allocated when the system 
booted (see below). This permits the existing memory area to remain untouched in order to safely 
copy its contents to storage. 

5.3. Installation 

The kernel crash dump utility is installed with the following command: 

sudo apt-get install linux-crashdump 

A reboot is then needed. 

5.4. Configuration 

No further configuration is required in order to have the kernel dump mechanism enabled. 

5.5. Verification 

To confirm that the kernel dump mechanism is enabled, there are a few things to verify. First, confirm 
that the crashkernel boot parameter is present (note: The following line has been split into two to fit 
the format of this document: 
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cat /proc/cmdline 

B00T_IMAGE=/vmlinuz-3 . 2 . 0-17-server root=/dev/mapper/PreciseS-root ro 
crashkernel=384M-2G: 64M, 2G- : 128M 

The crashkernel parameter has the following syntax: 

crashkernel=<rangel> : <sizel> [ , <range2> : <size2> , . . . ] [@offset] 

range=start- [ end] 'start' is inclusive and 'end' is exclusive. 

So for the crashkernel parameter found in /proc/cmdline we would have : 

crashkernel=384M-2G: 64M, 2G- : 128M 
The above value means: 

• if the RAM is smaller than 384M, then don't reserve anything (this is the "rescue" case) 

• if the RAM size is between 386M and 2G (exclusive), then reserve 64M 

• if the RAM size is larger than 2G, then reserve 128M 

Second, verify that the kernel has reserved the requested memory area for the kdump kernel by doing: 
dmesg | grep -i crash 

[ 0.000000] Reserving 64MB of memory at 800MB for crashkernel (System RAM: 1023MB) 

5.6. Testing the Crash Dump Mechanism 

Testing the Crash Dump Mechanism will cause a system reboot. In certain situations, this 
can cause data loss if the system is under heavy load. If you want to test the mechanism, 
make sure that the system is idle or under very light load. 

Verify that the SysRQ mechanism is enabled by looking at the value of the /proc/sys/kernel/sysrq 
kernel parameter : 

cat /proc/sys/kernel/sysrq 

If a value of 0 is returned the feature is disabled. Enable it with the following command : 

sudo sysctl -w kernel . sysrq=l 

Once this is done, you must become root, as just using sudo will not be sufficient. As the root 
user, you will have to issue the command echo c > /proc/sysrq-trigger. If you are using a network 
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connection, you will lose contact with the system. This is why it is better to do the test while being 
connected to the system console. This has the advantage of making the kernel dump process visible. 

A typical test output should look like the following : 



sudo -s 

[sudo] password for ubuntu: 

# echo c > /proc/sysrq-trigger 

31.659002] SysRq : Trigger a crash 

31.659749] BUG: unable to handle kernel NULL pointer dereference at (null) 
31.662668] IP: [<f f f f f f f f 8139f 166>] sysrq_handle_crash+0xl6/0x2 0 
31.662668] PGD 3bfb9067 PUD 368a7067 PMD 0 
31.662668] Oops: 0002 [#1] SMP 
31.662668] CPU 1 



The rest of the output is truncated, but you should see the system rebooting and somewhere in the log, 
you will see the following line : 

Begin: Saving vmcore from kernel crash . . . 

Once completed, the system will reboot to its normal operational mode. You will then find Kernel 
Crash Dump file in the /var/crash directory : 



Is /var/crash 

linux-image-3 . 0 . 0-12-server . 0 . crash 

5.7. Resources 



Kernel Crash Dump is a vast topic that requires good knowledge of the linux kernel. You can find 
more information on the topic here : 

• Kdump kernel documentation 1 ^. 

• The crash tool 14 

• Analyzing Linux Kernel Crash 15 (Based on Fedora, it still gives a good walkthrough of kernel dump 
analysis) 



http ://www .kernel .org/doc/Documentation/kdump/kdump .txt 

http://people.redhat.com/~anderson/ 

http://www.dedoimedo.com/computers/crash-analyze.html 
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Ubuntu features a comprehensive package management system for installing, upgrading, configuring, 
and removing software. In addition to providing access to an organized base of over 35,000 software 
packages for your Ubuntu computer, the package management facilities also feature dependency 
resolution capabilities and software update checking. 

Several tools are available for interacting with Ubuntu's package management system, from simple 
command-line utilities which may be easily automated by system administrators, to a simple graphical 
interface which is easy to use by those new to Ubuntu. 
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1. Introduction 

Ubuntu's package management system is derived from the same system used by the Debian GNU/ 
Linux distribution. The package files contain all of the necessary files, meta-data, and instructions to 
implement a particular functionality or software application on your Ubuntu computer. 

Debian package files typically have the extension '.deb', and usually exist in repositories which are 
collections of packages found on various media, such as CD-ROM discs, or online. Packages are 
normally in a pre-compiled binary format; thus installation is quick, and requires no compiling of 
software. 

Many complex packages use the concept of dependencies. Dependencies are additional packages 
required by the principal package in order to function properly. For example, the speech synthesis 
package festival depends upon the package libasound2, which is a package supplying the ALSA 
sound library needed for audio playback. In order for festival to function, it and all of its dependencies 
must be installed. The software management tools in Ubuntu will do this automatically. 
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2. dpkg 

dpkg is a package manager for Debian-based systems. It can install, remove, and build packages, but 
unlike other package management systems, it cannot automatically download and install packages or 
their dependencies. This section covers using dpkg to manage locally installed packages: 

• To list all packages installed on the system, from a terminal prompt type: 
dpkg -1 

• Depending on the amount of packages on your system, this can generate a large amount of output. 
Pipe the output through grep to see if a specific package is installed: 

dpkg -1 | grep apache2 

Replace apache2 with any package name, part of a package name, or other regular expression. 

• To list the files installed by a package, in this case the ufw package, enter: 

dpkg -L ufw 

• If you are not sure which package installed a file, dpkg -S may be able to tell you. For example: 



dpkg -S /etc/host . conf 

base-files: /etc/host . conf 

The output shows that the /etc/host. conf belongs to the base-files package. 



«— I Many files are automatically generated during the package install process, and even 

though they are on the filesystem, dpkg -S may not know which package they belong to. 

You can install a local .deb file by entering: 



sudo dpkg -i zip_3 . 0-4_i386 .deb 

Change zip_3 . 0-4_i386 .deb to the actual file name of the local .deb file you wish to install. 
Uninstalling a package can be accomplished by: 



sudo dpkg -r zip 



Uninstalling packages using dpkg, in most cases, is NOT recommended. It is better to use 
a package manager that handles dependencies to ensure that the system is in a consistent 
state. For example using dpkg -r zip will remove the zip package, but any packages that 
depend on it will still be installed and may no longer function correctly. 



For more dpkg options see the man page: man dpkg. 
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3. Apt-Get 

The apt-get command is a powerful command-line tool, which works with Ubuntu's Advanced 
Packaging Tool (APT) performing such functions as installation of new software packages, upgrade 
of existing software packages, updating of the package list index, and even upgrading the entire 
Ubuntu system. 

Being a simple command-line tool, apt- get has numerous advantages over other package management 
tools available in Ubuntu for server administrators. Some of these advantages include ease of use over 
simple terminal connections (SSH), and the ability to be used in system administration scripts, which 
can in turn be automated by the cron scheduling utility. 

Some examples of popular uses for the apt-get utility: 

• Install a Package: Installation of packages using the apt-get tool is quite simple. For example, to 
install the network scanner nmap, type the following: 

sudo apt-get install nmap 

• Remove a Package: Removal of a package (or packages) is also straightforward. To remove the 
package installed in the previous example, type the following: 

sudo apt-get remove nmap 




Multiple Packages: You may specify multiple packages to be installed or removed, 
separated by spaces. 



Also, adding the —purge option to apt-get remove will remove the package configuration files as 
well. This may or may not be the desired effect, so use with caution. 

• Update the Package Index: The APT package index is essentially a database of available 
packages from the repositories defined in the /etc/apt/sources. list file and in the /etc/apt/ 
sources . list . d directory. To update the local package index with the latest changes made in the 
repositories, type the following: 

sudo apt-get update 

• Upgrade Packages: Over time, updated versions of packages currently installed on your computer 
may become available from the package repositories (for example security updates). To upgrade 
your system, first update your package index as outlined above, and then type: 

sudo apt-get upgrade 

For information on upgrading to a new Ubuntu release see Section 3, "Upgrading" [p. 9]. 

Actions of the apt-get command, such as installation and removal of packages, are logged in the /var/ 
log/dpkg.log log file. 
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For further information about the use of APT, read the comprehensive Debian APT User Manual 1 or 
type: 

apt-get help 



http://www.debia11.0rg/doc/user-manuals#apt-howto 
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4. Aptitude 

Launching Aptitude with no command-line options, will give you a menu-driven, text-based front- 
end to the Advanced Packaging Tool (APT) system. Many of the common package management 
functions, such as installation, removal, and upgrade, can be performed in Aptitude with single -key 
commands, which are typically lowercase letters. 

Aptitude is best suited for use in a non-graphical terminal environment to ensure proper functioning 
of the command keys. You may start the menu-driven interface of Aptitude as a normal user by typing 
the following command at a terminal prompt: 

sudo aptitude 

When Aptitude starts, you will see a menu bar at the top of the screen and two panes below the menu 
bar. The top pane contains package categories, such as New Packages and Not Installed Packages. 
The bottom pane contains information related to the packages and package categories. 

Using Aptitude for package management is relatively straightforward, and the user interface makes 
common tasks simple to perform. The following are examples of common package management 
functions as performed in Aptitude: 

• Install Packages: To install a package, locate the package via the Not Installed Packages package 
category, by using the keyboard arrow keys and the ENTER key. Highlight the desired package, 
then press the + key. The package entry should turn green, indicating that it has been marked for 
installation. Now press g to be presented with a summary of package actions. Press g again, and 
downloading and installation of the package will commence. When finished, press ENTER, to 
return to the menu. 

• Remove Packages: To remove a package, locate the package via the Installed Packages package 
category, by using the keyboard arrow keys and the ENTER key. Highlight the desired package 
you wish to remove, then press the - key. The package entry should turn pink, indicating it has 
been marked for removal. Now press g to be presented with a summary of package actions. Press g 
again, and removal of the package will commence. When finished, press ENTER, to return to the 
menu. 

• Update Package Index: To update the package index, simply press the u key. Updating of the 
package index will commence. 

• Upgrade Packages: To upgrade packages, perform the update of the package index as detailed 
above, and then press the U key to mark all packages with updates. Now press g whereby you'll be 
presented with a summary of package actions. Press g again, and the download and installation will 
commence. When finished, press ENTER, to return to the menu. 

The first column of information displayed in the package list in the top pane, when actually viewing 
packages lists the current state of the package, and uses the following key to describe the state of the 
package: 
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• i: Installed package 

• c: Package not installed, but package configuration remains on system 

• p: Purged from system 

• v: Virtual package 

• B: Broken package 

• u: Unpacked files, but package not yet configured 

• C: Half-configured - Configuration failed and requires fix 

• H: Half-installed - Removal failed and requires fix 

To exit Aptitude, simply press the q key and confirm you wish to exit. Many other functions are 
available from the Aptitude menu by pressing the F10 key. 

4.1 . Command Line Aptitude 

You can also use Aptitude as a command-line tool, similar to apt-get. To install the nmap package 
with all necessary dependencies, as in the apt-get example, you would use the following command: 

sudo aptitude install nmap 

To remove the same package, you would use the command: 
sudo aptitude remove nmap 

Consult the man pages for more details of command line options for Aptitude. 
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5. Automatic Updates 

The unattended-upgrades package can be used to automatically install updated packages, and can be 
configured to update all packages or just install security updates. First, install the package by entering 
the following in a terminal: 



sudo apt-get install unattended-upgrades 

To configure unattended-upgrades, edit /etc/apt/apt. conf.d/50unattended-upgrades and adjust 
the following to fit your needs: 



Unattended-Upgrade: : Allowed-Origins { 

"Ubuntu trusty-security" ; 
// "Ubuntu trusty-updates"; 

}; 

Certain packages can also be blacklisted and therefore will not be automatically updated. To blacklist 
a package, add it to the list: 



Unattended-Upgrade: : Package-Blacklist { 

// "vim"; 

// "libc6"; 

// "libc6-dev" ; 

// "Iibc6-i686"; 

}; 

*— i The double "//" serve as comments, so whatever follows "//" will not be evaluated. 



To enable automatic updates, edit /etc/apt/apt. conf .d/ioperiodic and set the appropriate apt 
configuration options: 



APT : : Periodic : : Update-Package-Lists " 1 " ; 

APT : : Periodic : : Download-Upgradeable-Packages " 1 " ; 

APT : : Periodic : : Autocleanlnterval " 7 " ; 

APT : : Periodic : : Unattended-Upgrade " 1 " ; 



The above configuration updates the package list, downloads, and installs available upgrades every 
day. The local download archive is cleaned every week. 

a— I You can read more about apt Periodic configuration options in the /etc/cron. daily/apt 

l C I E 

script header. 

The results of unattended-upgrades will be logged to /var/iog/unattended-upgrades. 
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5.1. Notifications 

Configuring Unattended-Upgrade: :Mail in /etc/apt/apt. conf.d/50unattended-upgrades will 
enable unattended-upgrades to email an administrator detailing any packages that need upgrading or 
have problems. 

Another useful package is apticron. apticron will configure a cron job to email an administrator 
information about any packages on the system that have updates available, as well as a summary of 
changes in each package. 

To install the apticron package, in a terminal enter: 
sudo apt-get install apticron 

Once the package is installed edit /etc/apticron/apticron.conf , to set the email address and other 
options: 

EMAIL="root@example . com" 
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6. Configuration 

Configuration of the Advanced Packaging Tool (APT) system repositories is stored in the /etc /apt/ 
sources, list file and the /etc/apt/sources, list, d directory. An example of this file is referenced 
here, along with information on adding or removing repository references from the file. 

You may edit the file to enable repositories or disable them. For example, to disable the requirement 
of inserting the Ubuntu CD-ROM whenever package operations occur, simply comment out the 
appropriate line for the CD-ROM, which appears at the top of the file: 



# no more prompting for CD-ROM please 

# deb cdrom: [Ubuntu 14.04 JTrusty Tahr_ - Release i386 (20111013.1)]/ trusty main restricted 

6.1 . Extra Repositories 

In addition to the officially supported package repositories available for Ubuntu, there exist additional 
community-maintained repositories which add thousands more packages for potential installation. 
Two of the most popular are the Universe and Multiverse repositories. These repositories are not 
officially supported by Ubuntu, but because they are maintained by the community they generally 
provide packages which are safe for use with your Ubuntu computer. 
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Packages in the Multiverse repository often have licensing issues that prevent them from 
being distributed with a free operating system, and they may be illegal in your locality. 

Be advised that neither the Universe or Multiverse repositories contain officially supported 
packages. In particular, there may not be security updates for these packages. 

Many other package sources are available, sometimes even offering only one package, as in the case 
of package sources provided by the developer of a single application. You should always be very 
careful and cautious when using non-standard package sources, however. Research the source and 
packages carefully before performing any installation, as some package sources and their packages 
could render your system unstable or non-functional in some respects. 

By default, the Universe and Multiverse repositories are enabled but if you would like to disable them 
edit /etc/apt/sources . list and comment the following lines: 



deb http://archive.ubuntu.com/ubuntu trusty universe multiverse 
deb-src http://archive.ubuntu.com/ubuntu trusty universe multiverse 

deb http://us.archive.ubuntu.com/ubuntu/ trusty universe 
deb-src http://us.archive.ubuntu.com/ubuntu/ trusty universe 
deb http://us.archive.ubuntu.com/ubuntu/ trusty-updates universe 
deb-src http://us.archive.ubuntu.com/ubuntu/ trusty-updates universe 

deb http://us.archive.ubuntu.com/ubuntu/ trusty multiverse 
deb-src http://us.archive.ubuntu.com/ubuntu/ trusty multiverse 
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deb http://us.archive.ubuntu.com/ubuntu/ trusty-updates multiverse 
deb-src http://us.archive.ubuntu.com/ubuntu/ trusty-updates multiverse 

deb http://security.ubuntu.com/ubuntu trusty-security universe 
deb-src http://security.ubuntu.com/ubuntu trusty-security universe 
deb http://security.ubuntu.com/ubuntu trusty-security multiverse 
deb-src http://security.ubuntu.com/ubuntu trusty-security multiverse 
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7. References 

Most of the material covered in this chapter is available in man pages, many of which are available 
online. 

• The InstallingSoftware 2 Ubuntu wiki page has more information. 

• For more dpkg details see the dpkg man page 3 . 

• The APT HOWTO 4 and apt-get man page 5 contain useful information regarding apt-get usage. 

• See the aptitude man page 6 for more aptitude options. 

• The Adding Repositories HOWTO (Ubuntu Wiki) 7 page contains more details on adding 
repositories. 



https://help.ubuntu.com/community/InstallingSoftware 

http://manpages.ubuntu.eom/manpages/trasty/en/manl/dpkg.l.html 

http://www.debian.org/doc/manuals/apt-howto/ 

http://manpages.ubuntu.eom/manpages/trasty/en/man8/apt-get.8.html 

http://manpages.ubuntu.eom/manpages/trasty/man8/aptitude.8.html 

https://help.ubuntu.com/community/Repositories/Ubuntu 
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Networks consist of two or more devices, such as computer systems, printers, and related equipment 
which are connected by either physical cabling or wireless links for the purpose of sharing and 
distributing information among the connected devices. 

This section provides general and specific information pertaining to networking, including an 
overview of network concepts and detailed discussion of popular network protocols. 
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1. Network Configuration 

Ubuntu ships with a number of graphical utilities to configure your network devices. This document is 
geared toward server administrators and will focus on managing your network on the command line. 

1.1. Ethernet Interfaces 

Ethernet interfaces are identified by the system using the naming convention of ethX, where X 
represents a numeric value. The first Ethernet interface is typically identified as ethO, the second as 
ethl, and all others should move up in numerical order. 

1.1.1. Identify Ethernet Interfaces 

To quickly identify all available Ethernet interfaces, you can use the ifconfig command as shown 
below. 

Ifconfig -a | grep eth 

ethO Link encap: Ethernet HWaddr 00 : 15 : c5 : 4a: 16 : 5a 

Another application that can help identify all network interfaces available to your system is the lshw 
command. In the example below, lshw shows a single Ethernet interface with the logical name of ethO 
along with bus information, driver details and all supported capabilities. 

sudo lshw -class network 

* -network 

description: Ethernet interface 

product: BCM4401-B0 100Base-TX 

vendor: Broadcom Corporation 

physical id: 0 

bus info: pci@0000 : 03 : 00 . 0 

logical name: ethO 

version: 02 

serial: 00 : 15 : c5 : 4a: 16 : 5a 
size: lOMB/s 
capacity: lOOMB/s 
width: 32 bits 
clock: 33MHz 

capabilities: (snipped for brevity) 
configuration: (snipped for brevity) 
resources: irq:17 memory:ef 9f eOOO-ef 9f f f f f 

1.1.2. Ethernet Interface Logical Names 

Interface logical names are configured in the file /etc/udev/rules.d/70-persistent-net. rules. If 
you would like control which interface receives a particular logical name, find the line matching the 
interfaces physical MAC address and modify the value of NAME=ethX to the desired logical name. 
Reboot the system to commit your changes. 
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1.1.3. Ethernet Interface Settings 

ethtool is a program that displays and changes Ethernet card settings such as auto-negotiation, port 
speed, duplex mode, and Wake-on-LAN. It is not installed by default, but is available for installation 
in the repositories. 

sudo apt-get install ethtool 

The following is an example of how to view supported features and configured settings of an Ethernet 
interface. 

sudo ethtool ethO 

Settings for ethO : 

Supported ports : [ TP ] 

Supported link modes: lObaseT/Half 10baseT/Full 

100baseT/Half lOObaseT/Full 

1000baseT/Half 1000baseT/Full 
Supports auto-negotiation: Yes 

Advertised link modes: lObaseT/Half 10baseT/Full 

100baseT/Half lOObaseT/Full 

1000baseT/Half 1000baseT/Full 
Advertised auto-negotiation: Yes 
Speed: lOOOMb/s 
Duplex: Full 
Port: Twisted Pair 
PHYAD : 1 

Transceiver: internal 
Auto-negotiation: on 
Supports Wake-on: g 
Wake-on: d 

Current message level: OxOOOOOOff (255) 
Link detected: yes 

Changes made with the ethtool command are temporary and will be lost after a reboot. If you would 
like to retain settings, simply add the desired ethtool command to a pre-up statement in the interface 
configuration file /etc/network/interfaces. 

The following is an example of how the interface identified as ethO could be permanently configured 
with a port speed of lOOOMb/s running in full duplex mode. 

auto ethO 

iface ethO inet static 

pre-up /sbin/ethtool -s ethO speed 1000 duplex full 

Although the example above shows the interface configured to use the static method, 
it actually works with other methods as well, such as DHCP. The example is meant to 
demonstrate only proper placement of the pre-up statement in relation to the rest of the 
interface configuration. 
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1.2. IP Addressing 

The following section describes the process of configuring your systems IP address and default 
gateway needed for communicating on a local area network and the Internet. 

1.2.1. Temporary IP Address Assignment 

For temporary network configurations, you can use standard commands such as ip, ifconfig and route, 
which are also found on most other GNU/Linux operating systems. These commands allow you to 
configure settings which take effect immediately, however they are not persistent and will be lost after 
a reboot. 

To temporarily configure an IP address, you can use the ifconfig command in the following manner. 
Just modify the IP address and subnet mask to match your network requirements. 

sudo ifconfig ethO 10.0.0.100 netmask 255.255.255.0 

To verify the IP address configuration of ethO, you can use the ifconfig command in the following 
manner. 



ifconfig ethO 

ethO Link encap: Ethernet HWaddr 00 : 15 : c5 : 4a : 16 : 5a 

inet addr : 10 . 0 . 0 . 100 Beast : 10 . 0 . 0 . 255 Mask: 255 . 255 . 255 . 0 

inet6 addr: f e80 : : 215 :c5f f : f e4a: 165a/64 Scope:Link 

UP BROADCAST RUNNING MULTICAST MTU: 1500 Metric : 1 

RX packets : 466475604 errors:0 dropped:0 overruns : 0 frame:0 

TX packets:403172654 errors : 0 dropped:0 overruns : 0 carrier:0 

collisions :0 txqueuelen: 1000 

RX bytes:2574778386 (2.5 GB) TX bytes : 1618367329 (1.6 GB) 
Interrupt : 16 

To configure a default gateway, you can use the route command in the following manner. Modify the 
default gateway address to match your network requirements. 



sudo route add default gw 10.0.0.1 ethO 

To verify your default gateway configuration, you can use the route command in the following 
manner. 



route -n 

Kernel IP routing table 

Destination Gateway Genmask Flags Metric Ref Use Iface 

10.0.0.0 0.0.0.0 255.255.255.0 U 1 0 0 ethO 

0.0.0.0 10.0.0.1 0.0.0.0 UG 0 0 0 ethO 

If you require DNS for your temporary network configuration, you can add DNS server IP addresses 
in the file /etc/resolv.conf . In general, editing /etc/resolv.conf directly is not recommanded, 
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but this is a temporary and non-persistent configuration. The example below shows how to enter 
two DNS servers to /etc/resoiv.conf , which should be changed to servers appropriate for your 
network. A more lengthy description of the proper persistent way to do DNS client configuration is in 
a following section. 

nameserver 8.8.8.8 
nameserver 8.8.4.4 

If you no longer need this configuration and wish to purge all IP configuration from an interface, you 
can use the ip command with the flush option as shown below. 

ip addr flush ethO 

*— I Flushing the IP configuration using the ip command does not clear the contents of /etc/ 

resoiv.conf . You must remove or modify those entries manually, or re-boot which should 
also cause /etc/resolv.conf , which is actually now a symlink to /run/resolvconf / 
resoiv.conf , to be re-written. 

1.2.2. Dynamic IP Address Assignment (DHCP Client) 

To configure your server to use DHCP for dynamic address assignment, add the dhcp method to the 
inet address family statement for the appropriate interface in the file /etc/network/interfaces. The 
example below assumes you are configuring your first Ethernet interface identified as ethO. 

auto ethO 

iface ethO inet dhcp 

By adding an interface configuration as shown above, you can manually enable the interface through 
the ifup command which initiates the DHCP process via dhclient. 

sudo Ifup ethO 

To manually disable the interface, you can use the if down command, which in turn will initiate the 
DHCP release process and shut down the interface. 

sudo if down ethO 

1.2.3. Static IP Address Assignment 

To configure your system to use a static IP address assignment, add the static method to the inet 
address family statement for the appropriate interface in the file /etc/network/interfaces. The 
example below assumes you are configuring your first Ethernet interface identified as ethO. Change 
the address, netmask, and gateway values to meet the requirements of your network. 
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auto ethO 

iface ethO inet static 
address 10.0.0.100 
netmask 255.255.255.0 
gateway 10.0.0.1 

By adding an interface configuration as shown above, you can manually enable the interface through 
the ifup command. 

sudo Ifup ethO 

To manually disable the interface, you can use the if down command. 

sudo if down ethO 

1.2.4. Loopback Interface 

The loopback interface is identified by the system as lo and has a default IP address of 127.0.0.1 . It 
can be viewed using the ifconfig command. 

ifconfig lo 

lo Link encap: Local Loopback 

inet addr : 127 . 0 . 0 . 1 Mask : 255 . 0 . 0 . 0 

inet6 addr: :: 1/128 Scope:Host 

UP LOOPBACK RUNNING MTU: 16436 Metric : 1 

RX packets: 27 18 errors : 0 dropped :0 overruns : 0 frame :0 

TX packets: 27 18 errors :0 dropped :0 overruns : 0 carrier :0 

collisions :0 txqueuelen:0 

RX bytes:183308 (183.3 KB) TX bytes:183308 (183.3 KB) 

By default, there should be two lines in /etc/network/interfaces responsible for automatically 
configuring your loopback interface. It is recommended that you keep the default settings unless you 
have a specific purpose for changing them. An example of the two default lines are shown below. 

auto lo 

iface lo inet loopback 

1.3. Name Resolution 

Name resolution as it relates to IP networking is the process of mapping IP addresses to hostnames, 
making it easier to identify resources on a network. The following section will explain how to 
properly configure your system for name resolution using DNS and static hostname records. 

1.3.1. DNS Client Configuration 

Traditionally, the file /etc/resolv.conf was a static configuration file that rarely needed to be 
changed or automatically changed via DCHP client hooks. Nowadays, a computer can switch from 



37 



Networking 



one network to another quite often and the resolvconf framework is now being used to track these 
changes and update the resolver's configuration automatically. It acts as an intermediary between 
programs that supply nameserver information and applications that need nameserver information. 
Resolvconf gets populated with information by a set of hook scripts related to network interface 
configuration. The most notable difference for the user is that any change manually done to /etc/ 
resolv.conf will be lost as it gets overwritten each time something triggers resolvconf. Instead, 
resolvconf uses DHCP client hooks, and /etc /network/ interfaces to generate a list of nameservers 
and domains to put in /etc/resolv.conf , which is now a symlink: 

/etc/resolv . conf -> . . /run/resolvconf /resolv . conf 

To configure the resolver, add the IP addresses of the nameservers that are appropriate for your 
network in the file /etc/network/interfaces. You can also add an optional DNS suffix search-lists 
to match your network domain names. For each other valid resolv.conf configuration option, you can 
include, in the stanza, one line beginning with that option name with a dns- prefix. The resulting file 
might look like the following: 

iface ethO inet static 
address 192.168.3.3 
netmask 255.255.255.0 
gateway 192.168.3.1 
dns-search example.com 

dns-nameservers 192.168.3.45 192.168.8.10 

The search option can also be used with multiple domain names so that DNS queries will be 
appended in the order in which they are entered. For example, your network may have multiple sub- 
domains to search; a parent domain of example.com, and two sub-domains, sales.example.com and 
dev .example .com . 

If you have multiple domains you wish to search, your configuration might look like the following: 

iface ethO inet static 
address 192.168.3.3 
netmask 255.255.255.0 
gateway 192.168.3.1 

dns-search example.com sales.example.com dev.example.com 
dns-nameservers 192.168.3.45 192.168.8.10 

If you try to ping a host with the name of server 1 , your system will automatically query DNS for its 
Fully Qualified Domain Name (FQDN) in the following order: 

1. serverl.example.com 

2 . server 1 .sales .example .com 

3 . server 1 .dev .example .com 

If no matches are found, the DNS server will provide a result of notfound and the DNS query will fail. 
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1.3.2. Static Hostnames 

Static hostnames are locally defined hostname-to-IP mappings located in the file /etc/hosts. 
Entries in the hosts file will have precedence over DNS by default. This means that if your system 
tries to resolve a hostname and it matches an entry in /etc/hosts, it will not attempt to look up the 
record in DNS. In some configurations, especially when Internet access is not required, servers that 
communicate with a limited number of resources can be conveniently set to use static hostnames 
instead of DNS. 

The following is an example of a hosts file where a number of local servers have been identified by 
simple hostnames, aliases and their equivalent Fully Qualified Domain Names (FQDN's). 



127.0.0.1 localhost 

127.0.1.1 ubuntu-server 

10.0.0.11 server 1 serverl.example.com vpn 

10.0.0.12 server2 server2.example.com mail 

10.0.0.13 server3 server3.example.com www 

10.0.0.14 server4 server4.example.com file 



*— I In the above example, notice that each of the servers have been given aliases in addition 
to their proper names and FQDN's. Server 1 has been mapped to the name vpn, server2 is 
referred to as mail, server 3 as www, and serve r4 as file. 

1 .3 .3 . Name Service Switch Configuration 

The order in which your system selects a method of resolving hostnames to IP addresses is controlled 
by the Name Service Switch (NSS) configuration file /etc/nsswitch.conf . As mentioned in the 
previous section, typically static hostnames defined in the systems /etc/hosts file have precedence 
over names resolved from DNS . The following is an example of the line responsible for this order of 
hostname lookups in the file /etc/nsswitch.conf. 



hosts: files mdns4_minimal [NOTFOUND=return] dns mdns4 

• files first tries to resolve static hostnames located in /etc/hosts. 

• mdns4_minimal attempts to resolve the name using Multicast DNS . 

• [NOTFOUND=return] means that any response of notfound by the preceding mdns4_minimal 
process should be treated as authoritative and that the system should not try to continue hunting for 
an answer. 

• dns represents a legacy unicast DNS query. 

• mdns4 represents a Multicast DNS query. 

To modify the order of the above mentioned name resolution methods, you can simply change the 
hosts: string to the value of your choosing. For example, if you prefer to use legacy Unicast DNS 
versus Multicast DNS, you can change the string in /etc/nsswitch.conf as shown below. 
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hosts: files dns [NOTFOUND=return] mdns4_minimal mdns4 

1.4. Bridging 

Bridging multiple interfaces is a more advanced configuration, but is very useful in multiple 
scenarios. One scenario is setting up a bridge with multiple network interfaces, then using a firewall 
to filter traffic between two network segments. Another scenario is using bridge on a system with 
one interface to allow virtual machines direct access to the outside network. The following example 
covers the latter scenario. 

Before configuring a bridge you will need to install the bridge-utils package. To install the package, in 
a terminal enter: 

sudo apt-get install bridge-utils 

Next, configure the bridge by editing /etc/network/interfaces: 
auto lo 

iface lo inet loopback 
auto brO 

iface brO inet static 

address 192.168.0.10 
network 192.168.0.0 
netmask 255.255.255.0 
broadcast 192.168.0.255 
gateway 192.168.0.1 
bridge_ports ethO 
bridge_fd 9 
bridge_hello 2 
bridge_maxage 12 
bridge_stp off 




Enter the appropriate values for your physical interface and network. 



Now bring up the bridge: 
sudo if up brO 

The new bridge interface should now be up and running. The brctl provides useful information about 
the state of the bridge, controls which interfaces are part of the bridge, etc. See man brctl for more 
information. 

1 .5 . Resources 
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• The Ubuntu Wiki Network page 1 has links to articles covering more advanced network 
configuration. 

• The resolvconf man page 2 has more information on resolvconf. 

• The interfaces man page 3, has details on more options for /etc/network/interfaces. 

• The dhclient man page 4 has details on more options for configuring DHCP client settings. 

• For more information on DNS client configuration see the re solver man page 5 . Also, Chapter 6 
of O'Reilly's Linux Network Administrator's Guide 6 is a good source of resolver and name service 
configuration information. 

• For more information on bridging see the brctl man page 1 and the Linux Foundation's Networking- 
Bridge" page. 



https://help.ubuntu.com/community/Network 

http://manpages.ubuntu.eom/manpages/man8/resolvconf.8.html 

http://manpages.ubuntu.eom/manpages/man5/interfaces.5.html 

http://manpages.ubuntu.eom/manpages/man8/dhclient.8.html 

http://manpages.ubuntu.eom/manpages/man5/resolver.5.html 

http://oreilly.com/catalog/linag2/book/ch06.html 

http://manpages.ubuntu.eom/manpages/man8/brctl.8.html 

http://www.linuxfoundation.org/collaborate/workgroups/networking/bridge 



41 



Networking 



2. TCP/IP 



The Transmission Control Protocol and Internet Protocol (TCP/IP) is a standard set of protocols 
developed in the late 1970s by the Defense Advanced Research Projects Agency (DARPA) as a 
means of communication between different types of computers and computer networks. TCP/IP is the 
driving force of the Internet, and thus it is the most popular set of network protocols on Earth. 

2.1 . TCP/IP Introduction 



The two protocol components of TCP/IP deal with different aspects of computer networking. Internet 
Protocol, the "IP" of TCP/IP is a connectionless protocol which deals only with network packet 
routing using the IP Datagram as the basic unit of networking information. The IP Datagram consists 
of a header followed by a message. The Transmission Control Protocol is the "TCP" of TCP/IP and 
enables network hosts to establish connections which may be used to exchange data streams. TCP 
also guarantees that the data between connections is delivered and that it arrives at one network host 
in the same order as sent from another network host. 

2.2. TCP/IP Configuration 

The TCP/IP protocol configuration consists of several elements which must be set by editing the 
appropriate configuration files, or deploying solutions such as the Dynamic Host Configuration 
Protocol (DHCP) server which in turn, can be configured to provide the proper TCP/IP configuration 
settings to network clients automatically. These configuration values must be set correctly in order to 
facilitate the proper network operation of your Ubuntu system. 

The common configuration elements of TCP/IP and their purposes are as follows: 

• IP address The IP address is a unique identifying string expressed as four decimal numbers 
ranging from zero (0) to two- hundred and fifty-five (255), separated by periods, with each of the 
four numbers representing eight (8) bits of the address for a total length of thirty-two (32) bits for 
the whole address. This format is called dotted quad notation. 

• Netmask The Subnet Mask (or simply, netmask) is a local bit mask, or set of flags which separate 
the portions of an IP address significant to the network from the bits significant to the subnetwork. 
For example, in a Class C network, the standard netmask is 255.255.255.0 which masks the first 
three bytes of the IP address and allows the last byte of the IP address to remain available for 
specifying hosts on the subnetwork. 

• Network Address The Network Address represents the bytes comprising the network portion 
of an IP address. For example, the host 12.128.1 .2 in a Class A network would use 12.0.0.0 as 
the network address, where twelve (12) represents the first byte of the IP address, (the network 
part) and zeroes (0) in all of the remaining three bytes to represent the potential host values. A 
network host using the private IP address 192.168.1 .100 would in turn use a Network Address of 
192.168.1.0, which specifies the first three bytes of the Class C 192.168.1 network and a zero (0) 
for all the possible hosts on the network. 
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• Broadcast Address The Broadcast Address is an IP address which allows network data to be sent 
simultaneously to all hosts on a given subnetwork rather than specifying a particular host. The 
standard general broadcast address for IP networks is 255.255.255.255, but this broadcast address 
cannot be used to send a broadcast message to every host on the Internet because routers block 

it. A more appropriate broadcast address is set to match a specific subnetwork. For example, on 
the private Class C IP network, 192.168.1.0, the broadcast address is 192.168.1.255. Broadcast 
messages are typically produced by network protocols such as the Address Resolution Protocol 
(ARP) and the Routing Information Protocol (RIP). 

• Gateway Address A Gateway Address is the IP address through which a particular network, 
or host on a network, may be reached. If one network host wishes to communicate with another 
network host, and that host is not located on the same network, then a gateway must be used. In 
many cases, the Gateway Address will be that of a router on the same network, which will in turn 
pass traffic on to other networks or hosts, such as Internet hosts. The value of the Gateway Address 
setting must be correct, or your system will not be able to reach any hosts beyond those on the same 
network. 

• Nameserver Address Nameserver Addresses represent the IP addresses of Domain Name Service 
(DNS) systems, which resolve network hostnames into IP addresses. There are three levels of 
Nameserver Addresses, which may be specified in order of precedence: The Primary Nameserver, 
the Secondary Nameserver, and the Tertiary Nameserver. In order for your system to be able 

to resolve network hostnames into their corresponding IP addresses, you must specify valid 
Nameserver Addresses which you are authorized to use in your system's TCP/IP configuration. In 
many cases these addresses can and will be provided by your network service provider, but many 
free and publicly accessible nameservers are available for use, such as the LeveB (Verizon) servers 
with IP addresses from 4.2.2.1 to 4.2.2.6. 

4^ The IP address, Netmask, Network Address, Broadcast Address, Gateway Address, and 
Nameserver Addresses are typically specified via the appropriate directives in the file 
/etc/network/interfaces. For more information, view the system manual page for 
interfaces, with the following command typed at a terminal prompt: 

Access the system manual page for interfaces with the following command: 
man interfaces 

23. IP Routin g 

IP routing is a means of specifying and discovering paths in a TCP/IP network along which network 
data may be sent. Routing uses a set of routing tables to direct the forwarding of network data packets 
from their source to the destination, often via many intermediary network nodes known as routers. 
There are two primary forms of IP routing: Static Routing and Dynamic Routing. 

Static routing involves manually adding IP routes to the system's routing table, and this is usually 
done by manipulating the routing table with the route command. Static routing enjoys many 
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advantages over dynamic routing, such as simplicity of implementation on smaller networks, 
predictability (the routing table is always computed in advance, and thus the route is precisely the 
same each time it is used), and low overhead on other routers and network links due to the lack of 
a dynamic routing protocol. However, static routing does present some disadvantages as well. For 
example, static routing is limited to small networks and does not scale well. Static routing also fails 
completely to adapt to network outages and failures along the route due to the fixed nature of the 
route. 

Dynamic routing depends on large networks with multiple possible IP routes from a source to a 
destination and makes use of special routing protocols, such as the Router Information Protocol 
(RIP), which handle the automatic adjustments in routing tables that make dynamic routing possible. 
Dynamic routing has several advantages over static routing, such as superior scalability and the ability 
to adapt to failures and outages along network routes. Additionally, there is less manual configuration 
of the routing tables, since routers learn from one another about their existence and available routes. 
This trait also eliminates the possibility of introducing mistakes in the routing tables via human error. 
Dynamic routing is not perfect, however, and presents disadvantages such as heightened complexity 
and additional network overhead from router communications, which does not immediately benefit 
the end users, but still consumes network bandwidth. 



2.4. TCP and UDP 



TCP is a connection-based protocol, offering error correction and guaranteed delivery of data via 
what is known as flow control. Flow control determines when the flow of a data stream needs to be 
stopped, and previously sent data packets should to be re-sent due to problems such as collisions, 
for example, thus ensuring complete and accurate delivery of the data. TCP is typically used in the 
exchange of important information such as database transactions. 

The User Datagram Protocol (UDP), on the other hand, is a connectionless protocol which seldom 
deals with the transmission of important data because it lacks flow control or any other method to 
ensure reliable delivery of the data. UDP is commonly used in such applications as audio and video 
streaming, where it is considerably faster than TCP due to the lack of error correction and flow 
control, and where the loss of a few packets is not generally catastrophic. 



2.5.ICMP 



The Internet Control Messaging Protocol (ICMP) is an extension to the Internet Protocol (IP) as 
defined in the Request For Comments (RFC) #792 and supports network packets containing control, 
error, and informational messages. ICMP is used by such network applications as the ping utility, 
which can determine the availability of a network host or device. Examples of some error messages 
returned by ICMP which are useful to both network hosts and devices such as routers, include 
Destination Unreachable and Time Exceeded. 



44 



Networking 



2.6. Daemons 

Daemons are special system applications which typically execute continuously in the background and 
await requests for the functions they provide from other applications. Many daemons are network- 
centric; that is, a large number of daemons executing in the background on an Ubuntu system may 
provide network-related functionality. Some examples of such network daemons include the Hyper 
Text Transport Protocol Daemon (httpd), which provides web server functionality; the Secure SHell 
Daemon (sshd), which provides secure remote login shell and file transfer capabilities; and the 
Internet Message Access Protocol Daemon (imapd), which provides E-Mail services. 

2.7. Resources 

• There are man pages for TCP 9 and IP 10 that contain more useful information. 

• Also, see the TCP/IP Tutorial and Technical Overview 11 IBM Redbook. 

• Another resource is O'Reilly's TCP/IP Network Administration 12 . 



http://manpages.ubuntu.com/manpages/trasty/en/man7/tcp.7 .html 
http://manpages.ubuntu.eom/manpages/trasty/man7/ip.7.html 
http://www.redbooks.ibm.com/abstracts/gg243376.html 

2 http://oreilly.com/catalog/9780596002978/ 
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3. Dynamic Host Configuration Protocol (DHCP) 

The Dynamic Host Configuration Protocol (DHCP) is a network service that enables host computers 
to be automatically assigned settings from a server as opposed to manually configuring each network 
host. Computers configured to be DHCP clients have no control over the settings they receive from 
the DHCP server, and the configuration is transparent to the computer's user. 

The most common settings provided by a DHCP server to DHCP clients include: 

• IP address and netmask 

• IP address of the default-gateway to use 

• IP adresses of the DNS servers to use 

However, a DHCP server can also supply configuration properties such as: 

• Host Name 

• Domain Name 

• Time Server 

• Print Server 

The advantage of using DHCP is that changes to the network, for example a change in the address of 
the DNS server, need only be changed at the DHCP server, and all network hosts will be reconfigured 
the next time their DHCP clients poll the DHCP server. As an added advantage, it is also easier to 
integrate new computers into the network, as there is no need to check for the availability of an IP 
address. Conflicts in IP address allocation are also reduced. 

A DHCP server can provide configuration settings using the following methods: 

Manual allocation (MAC address) 

This method entails using DHCP to identify the unique hardware address of each network card 
connected to the network and then continually supplying a constant configuration each time the 
DHCP client makes a request to the DHCP server using that network device. This ensures that a 
particular address is assigned automatically to that network card, based on it's MAC address. 

Dynamic allocation (address pool) 

In this method, the DHCP server will assign an IP address from a pool of addresses (sometimes 
also called a range or scope) for a period of time or lease, that is configured on the server or 
until the client informs the server that it doesn't need the address anymore. This way, the clients 
will be receiving their configuration properties dynamically and on a "first come, first served" 
basis. When a DHCP client is no longer on the network for a specified period, the configuration 
is expired and released back to the address pool for use by other DHCP Clients. This way, an 
address can be leased or used for a period of time. After this period, the client has to renegociate 
the lease with the server to maintain use of the address. 

Automatic allocation 

Using this method, the DHCP automatically assigns an IP address permanently to a device, 
selecting it from a pool of available addresses. Usually DHCP is used to assign a temporary 
address to a client, but a DHCP server can allow an infinite lease time. 
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The last two methods can be considered "automatic" because in each case the DHCP server assigns 
an address with no extra intervention needed. The only difference between them is in how long the IP 
address is leased, in other words whether a client's address varies over time. Ubuntu is shipped with 
both DHCP server and client. The server is dhcpd (dynamic host configuration protocol daemon). 
The client provided with Ubuntu is dhclient and should be installed on all computers required to be 
automatically configured. Both programs are easy to install and configure and will be automatically 
started at system boot. 

3.1. Installation 

At a terminal prompt, enter the following command to install dhcpd: 



sudo apt-get Install isc-dhcp-server 

You will probably need to change the default configuration by editing /etc/dhcp/dhcpd.conf to suit 
your needs and particular configuration. 

You also may need to edit /etc/default/isc-dhcp-server to specify the interfaces dhcpd should listen to. 
NOTE: dhcpd's messages are being sent to syslog. Look there for diagnostics messages. 

3.2. Configuration 

The error message the installation ends with might be a little confusing, but the following steps will 
help you configure the service: 

Most commonly, what you want to do is assign an IP address randomly. This can be done with 
settings as follows: 

# minimal sample /etc/dhcp/dhcpd.conf 
default-lease-time 600; 
max-lease-time 7200; 

subnet 192.168.1.0 netmask 255.255.255.0 { 
range 192.168.1.150 192.168.1.200; 
option routers 192.168.1.254; 

option domain-name-servers 192.168.1.1, 192.168.1.2; 
option domain-name "mydomain . example" ; 

} 

This will result in the DHCP server giving clients an IP address from the range 
192.168.1.150-192.168.1.200. It will lease an IP address for 600 seconds if the client doesn't ask for 
a specific time frame. Otherwise the maximum (allowed) lease will be 7200 seconds. The server will 
also "advise" the client to use 192.168.1.254 as the default-gateway and 192.168.1.1 and 192.168.1.2 
as its DNS servers. 

After changing the config file you have to restart the dhcpd: 
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sudo service isc-dhcp-server restart 

3.3. References 

• The dhcp3-server Ubuntu Wiki 13 page has more information. 

• For more /etc/dhcp/dhcpd . conf options see the dhcpd.conf man page 

• ISC dhcp-server 15 



https://help.ubuntu.com/community/dhcp3-server 

http://manpages.ubuntu.eom/manpages/trusty/en/man5/dhcpd.conf.5.html 
http://www.isc.org/software/dhcp 
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4. Time Synchronisation with NTP 

NTP is a TCP/IP protocol for synchronising time over a network. Basically a client requests the 
current time from a server, and uses it to set its own clock. 

Behind this simple description, there is a lot of complexity - there are tiers of NTP servers, with the 
tier one NTP servers connected to atomic clocks, and tier two and three servers spreading the load 
of actually handling requests across the Internet. Also the client software is a lot more complex than 
you might think - it has to factor out communication delays, and adjust the time in a way that does not 
upset all the other processes that run on the server. But luckily all that complexity is hidden from you! 

Ubuntu uses ntpdate and ntpd. 

4.1. ntpdate 

Ubuntu comes with ntpdate as standard, and will run it once at boot time to set up your time according 
to Ubuntu's NTP server. 

ntpdate -s ntp.ubuntu.com 

4.2. ntpd 

The ntp daemon ntpd calculates the drift of your system clock and continuously adjusts it, so there 
are no large corrections that could lead to inconsistent logs for instance. The cost is a little processing 
power and memory, but for a modern server this is negligible. 

4.3. Installation 

To install ntpd, from a terminal prompt enter: 
sudo apt-get install ntp 

4.4. Configuration 

Edit /etc/ntp.conf to add/remove server lines. By default these servers are configured: 

# Use servers from the NTP Pool Project. Approved by Ubuntu Technical Board 

# on 2011-02-08 (LP: #104525). See http://www.pool.ntp.org/join.html for 

# more information. 

server 0 . ubuntu . pool . ntp . org 
server 1 .ubuntu .pool . ntp . org 
server 2 . ubuntu .pool . ntp. org 
server 3 .ubuntu .pool . ntp . org 

After changing the config file you have to reload the ntpd: 
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sudo service ntp reload 

4.5. View status 

Use ntpq to see more info: 



# sudo ntpq -p 
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4.6. References 

• See the Ubuntu Time 16 wiki page for more information. 

• ntp.org, home of the Network Time Protocol project 11 



https://help.ubuntu.com/community/UbuntuTime 
http://www.ntp.org/ 
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1. Device Mapper Multipathing 

Device mapper multipathing (DM-Multipath) allows you to configure multiple I/O paths between 
server nodes and storage arrays into a single device. These I/O paths are physical SAN connections 
that can include separate cables, switches, and controllers. Multipathing aggregates the I/O paths, 
creating a new device that consists of the aggregated paths. This chapter provides a summary of the 
features of DM-Multipath that are new for the initial release of Ubuntu Server 12.04. Following 
that, this chapter provides a high-level overview of DM Multipath and its components, as well as an 
overview of DM-Multipath setup. 

1.1. New and Changed Features for Ubuntu Server 12.04 

Migrated from multipath-0.4.8 to multipath-0.4.9 
1.1.1. Migration from 0.4.8 

The priority checkers are no longer run as standalone binaries, but as shared libraries. The key value 
name for this feature has also slightly changed. Copy the attribute named prio_callout to prio, also 
modify the argument the name of the priority checker, a system path is no longer necessary. Example 
conversion: 

device { 

vendor "NEC" 
product "DISK ARRAY" 

prio_callout mpath_prio_alua /dev/%n 
prio alua 

} 

See Table Priority Checker Conversion [p. 52] for a complete listing 



Table 5.1. Priority Checker Conversion 



vO.4.8 


vO.4.9 


prio_callout mpath_prio_emc /dev/%n 


prio emc 


prio_callout mpath_prio_alua /dev/%n 


prio alua 


prio_callout mpath_prio_netapp /dev/%n 


prio netapp 


prio_callout mpath_prio_rdac /dev/%n 


prio rdac 


prio_callout mpath_prio_hp_sw /dev/%n 


prio hp_sw 


prio_callout mpath_prio_hds_modular %b 


prio hds 



Since the multipath config file parser essentially parses all key/value pairs it finds and then makes use 
of them, it is safe for both prio_callout and prio to coexist and is recommended that the prio attribute 
be inserted before beginning migration. After which you can safely delete the legacy prio_calliout 
attribute without interrupting service. 
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1.2. Overview 

DM-Multipath can be used to provide: 

• Redundancy DM-Multipath can provide failover in an active/passive configuration. In an active/ 
passive configuration, only half the paths are used at any time for I/O. If any element of an I/O path 
(the cable, switch, or controller) fails, DM-Multipath switches to an alternate path. 

• Improved Performance Performance DM-Multipath can be configured in active/active mode, 
where I/O is spread over the paths in a round-robin fashion. In some configurations, DM-Multipath 
can detect loading on the I/O paths and dynamically re-balance the load. 

1.3. Storage Array Overview 

By default, DM-Multipath includes support for the most common storage arrays that support DM- 
Multipath. The supported devices can be found in the multipath.conf. defaults file. If your storage 
array supports DM-Multipath and is not configured by default in this file, you may need to add 
them to the DM-Multipath configuration file, multipath.conf. For information on the DM-Multipath 
configuration file, see Section, The DM-Multipath Configuration File. Some storage arrays require 
special handling of I/O errors and path switching. These require separate hardware handler kernel 
modules. 

1.4. DM-Multipath components 

Table DM-Multipath Components describes the components of the DM-Multipath package. 



Table 5.2. DM-Multipath Components 



Component 


Description 


dm_multipath kernel 
module 


Reroutes I/O and supports failover for paths and path groups. 


multipath command 


Lists and configures multipath devices. Normally started up with /etc/ 
rc . sysinit, it can also be started up by a udev program whenever a 
block device is added or it can be run by the initramfs file system. 


multipathd daemon 


Monitors paths; as paths fail and come back, it may initiate path group 
switches. Provides for interactive changes to multipath devices. This 
daemon must be restarted for any changes to the /etc/muitipath.conf 
file to take effect. 


kpartx command 


Creates device mapper devices for the partitions on a device It is 
necessary to use this command for DOS-based partitions with DM- 
Multipath. The kpartx is provided in its own package, but the multipath - 
tools package depends on it. 
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1.5. DM-Multipath Setup Overview 

DM-Multipath includes compiled-in default settings that are suitable for common multipath 
configurations. Setting up DM-multipath is often a simple procedure. The basic procedure for 
configuring your system with DM-Multipath is as follows: 

1 . Install the multipath-tools and multipath-tools-boot packages 

2. Create an empty config file, /etc/multipath.conf , that re-defines the following 

3. If necessary, edit the multipath .conf configuration file to modify default values and save the 
updated file. 

4. Start the multipath daemon 

5. Update initial ramdisk 

For detailed setup instructions for multipath configuration see Section, Setting Up DM-Multipath. 
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2. Multipath Devices 

Without DM-Multipath, each path from a server node to a storage controller is treated by the system 
as a separate device, even when the I/O path connects the same server node to the same storage 
controller. DM-Multipath provides a way of organizing the I/O paths logically, by creating a single 
multipath device on top of the underlying devices. 

2.1 . Multipath Device Identifiers 

Each multipath device has a World Wide Identifier (WWID), which is guaranteed to be globally 
unique and unchanging. By default, the name of a multipath device is set to its WWID. Alternately, 
you can set the user friendly _names option in the multipath configuration file, which causes DM- 
Multipath to use a node-unique alias of the form mpathn as the name. For example, a node with 
two HBAs attached to a storage controller with two ports via a single unzoned FC switch sees 
four devices: /dev/sda, /dev/sdb, /dev/sdc, and /dev/sdd. DM-Multipath creates a single device 
with a unique WWID that reroutes I/O to those four underlying devices according to the multipath 
configuration. When the user_friendly_names configuration option is set to yes, the name of the 
multipath device is set to mpathn. When new devices are brought under the control of DM-Multipath, 
the new devices may be seen in two different places under the /dev directory: /dev/mapper/mpathn 
and /dev/dm-n. 

• The devices in /dev/mapper are created early in the boot process. Use these devices to access the 
multipathed devices, for example when creating logical volumes. 

• Any devices of the form /dev/dm-n are for internal use only and should never be used. 

For information on the multipath configuration defaults, including the user_friendly_names 
configuration option, see Section , Configuration File Defaults. You can also set the name of a 
multipath device to a name of your choosing by using the alias option in the multipaths section of the 
multipath configuration file. For information on the multipaths section of the multipath configuration 
file, see Section, Multipaths Device Configuration Attributes. 

2.2. Consistent Multipath Device Names in a Cluster 

When the user_friendly_names configuration option is set to yes, the name of the multipath device 
is unique to a node, but it is not guaranteed to be the same on all nodes using the multipath device. 
Similarly, if you set the alias option for a device in the multipaths section of the multipath . conf 
configuration file, the name is not automatically consistent across all nodes in the cluster. This should 
not cause any difficulties if you use LVM to create logical devices from the multipath device, but if 
you require that your multipath device names be consistent in every node it is recommended that you 
leave the user_friendly_names option set to no and that you not configure aliases for the devices. 
By default, if you do not set user_friendly_names to yes or configure an alias for a device, a device 
name will be the WWID for the device, which is always the same. If you want the system-defined 
user-friendly names to be consistent across all nodes in the cluster, however, you can follow this 
procedure: 
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1. Set up all of the multipath devices on one machine. 

2. Disable all of your multipath devices on your other machines by running the following commands: 

# service multipath-tools stop 

# multipath -F 

3. Copy the /etc/multipath/bindings file from the first machine to all the other machines in the 
cluster. 

4. Re-enable the multipathd daemon on all the other machines in the cluster by running the following 
command: 

# service multipath-tools start 

If you add a new device, you will need to repeat this process. 

Similarly, if you configure an alias for a device that you would like to be consistent across the nodes 
in the cluster, you should ensure that the /etc/multipath.conf file is the same for each node in the 
cluster by following the same procedure: 

1 . Configure the aliases for the multipath devices in the in the multipath . conf file on one machine. 

2. Disable all of your multipath devices on your other machines by running the following commands: 

# service multipath-tools stop 

# multipath -F 

3. Copy the multipath . conf file from the first machine to all the other machines in the cluster. 

4. Re-enable the multipathd daemon on all the other machines in the cluster by running the following 
command: 

# service multipath-tools start 

When you add a new device you will need to repeat this process. 

2.3. Multipath Device attributes 

In addition to the user_friendly_names and alias options, a multipath device has numerous 
attributes. You can modify these attributes for a specific multipath device by creating an entry for 
that device in the multipaths section of the multipath configuration file. For information on the 
multipaths section of the multipath configuration file, see Section, "Configuration File Multipath 
Attributes" . 

2.4. Multipath Devices in Logical Volumes 

After creating multipath devices, you can use the multipath device names just as you would use a 
physical device name when creating an LVM physical volume. For example, if /dev/mapper/mpatha is 
the name of a multipath device, the following command will mark /dev/mapper/mpatha as a physical 
volume. 

# pvcreate /dev/mapper/mpatha 
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You can use the resulting LVM physical device when you create an LVM volume group just as you 
would use any other LVM physical device. 

If you attempt to create an LVM physical volume on a whole device on which you have 
configured partitions, the pvcreate command will fail. 

When you create an LVM logical volume that uses active/passive multipath arrays as the underlying 
physical devices, you should include filters in the lvm.conf to exclude the disks that underlie the 
multipath devices. This is because if the array automatically changes the active path to the passive 
path when it receives I/O, multipath will failover and fallback whenever LVM scans the passive path 
if these devices are not filtered. For active/passive arrays that require a command to make the passive 
path active, LVM prints a warning message when this occurs. To filter all SCSI devices in the LVM 
configuration file (lvm.conf), include the following filter in the devices section of the file. 

filter = [ "r/block/", "r/disk/", "r/sd.*/", "a/.*/" ] 

After updating /etc /lvm.conf , it's necessary to update the initrd so that this file will be copied there, 
where the filter matters the most, during boot. Perform: 

update-initramf s -u -k all 

Every time either /etc /lvm.conf or /etc/multipath.conf is updated, the initrd should be 
rebuilt to reflect these changes. This is imperative when blacklists and filters are necessary 
to maintain a stable storage configuration. 



57 



DM-Multipath 



3. Setting up DM-Multipath Overview 

This section provides step-by-step example procedures for configuring DM-Multipath. It includes the 
following procedures: 

• Basic DM-Multipath setup 

• Ignoring local disks 

• Adding more devices to the configuration file 

3.1. Setting Up DM-Multipath 

Before setting up DM-Multipath on your system, ensure that your system has been updated and 
includes the multipath-tools package. If boot from SAN is desired, then the multipath-tools-boot 

package is also required. 

A basic /etc/multipath.conf need not even exist, when multpath is run without an accompanying 
/etc/multipath.conf , it draws from it's internal database to find a suitable configuration, it also 
draws from it's internal blacklist. If after running multipath -11 without a config file, no multipaths are 
discovered. One must proceed to increase the verbosity to discover why a multipath was not created. 
Consider referencing the SAN vendor's documentation, the multipath example config files found in / 
usr/share/doc/multipath-toois/exampies, and the live multipathd database: 

• echo 'show config' | multipathd -k > multipath . conf -live 

To work around a quirk in multipathd, when an /etc/multipath.conf doesn't exist, the 
previous command will return nothing, as it is the result of a merge between the /etc/ 
multipath. conf and the database in memory. To remedy this, either define an empty /etc/ 
multipath . conf , by using touch, or create one that redefines a default value like: 

defaults { 

user_f riendly_names no 

} 

and restart multipathd: 

# service multipath-tools restart 

Now the "show config" command will return the live database. 

3.2. Installing with Multipath Support 

To enable multipath support during installation use 
install disk-detect /multipath/enable=true 

at the installer prompt. If multipath devices are found these will show up as /dev/mapper/mpath<X> 
during installation. 



' http://wiki.debian.org/DebianInstaller/MultipathSupport 
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3.3. Ignoring Local Disks When Generating Multipath Devices 

Some machines have local SCSI cards for their internal disks. DM-Multipath is not recommended 
for these devices. The following procedure shows how to modify the multipath configuration file to 
ignore the local disks when configuring multipath. 

1. Determine which disks are the internal disks and mark them as the ones to blacklist. In this 

example, /dev/sda is the internal disk. Note that as originally configured in the default multipath 
configuration file, executing the multipath -v2 shows the local disk, /dev/sda, in the multipath 
map. For further information on the multipath command output, see Section Multipath Command 
Output. 



# multipath -v2 

create: SIBM-ESXSST336732LC F3ET0EP0Q000072428BX1 undef WINSYS , SF2372 

size=33 GB features="0" hwhandler=" 0 " wp=undef 
"-+- policy= ' round-robin 0' prio=l status=undef 
| - 0:0:0:0 sda 8 : 0 [ 

device-mapper ioctl cmd 9 failed: Invalid argument 
device-mapper ioctl cmd 14 failed: No such device or address 
create: 3600a0b80001327d80000006d43621677 undef WINSYS , SF2372 
size=12G features='0' hwhandler= ' 0 ' wp=undef 
"-+- policy= ' round-robin 0' prio=l status=undef 
|- 2:0:0:0 sdb 8:16 undef ready running 
3:0:0:0 sdf 8:80 undef ready running 

create: 3600a0b80001327510000009a436215ec undef WINSYS , SF2372 
size=12G f eatures= ' 0 ' hwhandler= ' 0 ' wp=undef 
"-+- policy= ' round-robin 0' prio=l status=undef 
|- 2:0:0:1 sdc 8:32 undef ready running 

3:0:0:1 sdg 8:96 undef ready running 



create: 3600a0b80001327d800000070436216b3 undef WINSYS , SF2372 
size=12G features='0' hwhandler= ' 0 ' wp=undef 
"-+- policy= ' round-robin 0' prio=l status=undef 
|- 2:0:0:2 sdd 8:48 undef ready running 

3:0:0:2 sdg 8:112 undef ready running 



create: 3600a0b80001327510000009b4362163e undef WINSYS , SF2372 
size=12G features='0' hwhandler= ' 0 ' wp=undef 
"-+- policy= ' round-robin 0' prio=l status=undef 
|- 2:0:0:3 sdd 8:64 undef ready running 

3:0:0:3 sdg 8:128 undef ready running 

2. In order to prevent the device mapper from mapping /dev/sda in its multipath maps, edit the 
blacklist section of the /etc /multipath. conf file to include this device. Although you could 
blacklist the sda device using a devnode type, that would not be safe procedure since /dev/sda is 
not guaranteed to be the same on reboot. To blacklist individual devices, you can blacklist using 
the WWID of that device. Note that in the output to the multipath -v2 command, the WWID of 
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the /dev/sda device is SIBM-ESXSST336732LC F3ET0EP0Q000072428BX1. To blacklist 

this device, include the following in the /etc/muitipath.conf file. 

blacklist { 

wwid SIBM-ESXSST336732LC F3ET0EP0Q000072428BX1 

} 

3. After you have updated the /etc/multipath.conf file, you must manually tell the multipathd 
daemon to reload the file. The following command reloads the updated /etc/multipath . conf file. 

# service multipath-tools reload 

4. Run the following command to remove the multipath device: 

# multipath -f SIBM-ESXSST336732LC F3ET0EP0Q000072428BX1 

5. To check whether the device removal worked, you can run the multipath -11 command to display 
the current multipath configuration. For information on the multipath -11 command, see Section 
Multipath Queries with multipath Command. To check that the blacklisted device was not added 
back, you can run the multipath command, as in the following example. The multipath command 
defaults to a verbosity level of v2 if you do not specify a -v option. 

# multipath 

create: 3600a0b80001327d80000006d43621677 undef WINSYS , SF2372 
size=12G features='0' hwhandler= ' 0 ' wp=undef 
"-+- policy= ' round-robin 0' prio=l status=undef 
|- 2:0:0:0 sdb 8:16 undef ready running 
3:0:0:0 sdf 8:80 undef ready running 

create: 3600a0b80001327510000009a436215ec undef WINSYS , SF2372 
size=12G f eatures= ' 0 ' hwhandler= ' 0 ' wp=undef 
"-+- policy= ' round-robin 0' prio=l status=undef 
|- 2:0:0:1 sdc 8:32 undef ready running 

3:0:0:1 sdg 8:96 undef ready running 

create: 3600a0b80001327d800000070436216b3 undef WINSYS , SF2372 
size=12G features='0' hwhandler= ' 0 ' wp=undef 
"-+- policy= ' round-robin 0' prio=l status=undef 
|- 2:0:0:2 sdd 8:48 undef ready running 

3:0:0:2 sdg 8:112 undef ready running 

create: 3600a0b80001327510000009b4362163e undef WINSYS , SF2372 
size=12G features='0' hwhandler= ' 0 ' wp=undef 
"-+- policy= ' round-robin 0' prio=l status=undef 
|- 2:0:0:3 sdd 8:64 undef ready running 

3:0:0:3 sdg 8:128 undef ready running 
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3.4. Configuring Storage Devices 

By default, DM-Multipath includes support for the most common storage arrays that support DM- 
Multipath. The default configuration values, including supported devices, can be found in the 
multipath.conf .defaults file. 

If you need to add a storage device that is not supported by default as a known multipath device, edit 
the /etc/multipath.conf file and insert the appropriate device information. 

For example, to add information about the HP Open-V series the entry looks like this, where %n is 
the device name: 

devices { 

device { 

vendor "HP" 
product "OPEN-V." 

getuid_callout " /lib/udev/scsi_id — whitelisted — device=/dev/%n" 

} 

} 

For more information on the devices section of the configuration file, see Section Configuration File 
Devices [p. 71]. 
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4. The DM-Multipath Configuration File 

By default, DM-Multipath provides configuration values for the most common uses of multipathing. 
In addition, DM-Multipath includes support for the most common storage arrays that support 
DM-Multipath. The default configuration values and the supported devices can be found in the 
multipath.conf .defaults file. 

You can override the default configuration values for DM-Multipath by editing the /etc/ 
multipath.conf configuration file. If necessary, you can also add a storage array that is not supported 
by default to the configuration file. This chapter provides information on parsing and modifying the 
multipath.conf file. It contains sections on the following topics: 

• Configuration File Overview [p. 62] 

• Configuration File Blacklist [p. 63] 

• Configuration File Defaults [p. 65] 

• Configuration File Multipath Attributes [p. 69] 

• Configuration File Devices [p. 71] 

In the multipath configuration file, you need to specify only the sections that you need 
for your configuration, or that you wish to change from the default values specified in the 
multipath . conf . defaults file. If there are sections of the file that are not relevant to your 
environment or for which you do not need to override the default values, you can leave them 
commented out, as they are in the initial file. 

The configuration file allows regular expression description syntax. 

An annotated version of the configuration file can be found in /usr/share/doc/multipath-toois/ 
examples /multipath . conf . annotated . gz . 

4.1. Configuration File Overview 

The multipath configuration file is divided into the following sections: 
blacklist 

Listing of specific devices that will not be considered for multipath. 
blacklist_exceptions 

Listing of multipath candidates that would otherwise be blacklisted according to the parameters of 
the blacklist section. 

defaults 

General default settings for DM-Multipath. 
multipath 

Settings for the characteristics of individual multipath devices. These values overwrite what is 
specified in the defaults and devices sections of the configuration file. 
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devices 

Settings for the individual storage controllers. These values overwrite what is specified in the 
defaults section of the configuration file. If you are using a storage array that is not supported by 
default, you may need to create a devices subsection for your array. 

When the system determines the attributes of a multipath device, first it checks the multipath settings, 
then the per devices settings, then the multipath system defaults. 

4.2. Configuration File Blacklist 

The blacklist section of the multipath configuration file specifies the devices that will not be used 
when the system configures multipath devices. Devices that are blacklisted will not be grouped into a 
multipath device. 

• If you do need to blacklist devices, you can do so according to the following criteria: 

• By WWID, as described Blacklisting By WWID [p. 63] 

• By device name, as described in Blacklisting By Device Name [p. 63] 

• By device type, as described in Blacklisting By Device Type [p. 64] 

By default, a variety of device types are blacklisted, even after you comment out the initial blacklist 
section of the configuration file. For information, see Blacklisting By Device Name [p. 63] 

4.2.1. Blacklisting By WWID 

You can specify individual devices to blacklist by their World-Wide IDentification with a wwid entry 
in the blacklist section of the configuration file. 

The following example shows the lines in the configuration file that would blacklist a device with a 
WWID of 26353900f02796769. 

blacklist { 

wwid 26353900f 02796769 

} 

4.2.2. Blacklisting By Device Name 

You can blacklist device types by device name so that they will not be grouped into a multipath 
device by specifying a devnode entry in the blacklist section of the configuration file. 

The following example shows the lines in the configuration file that would blacklist all SCSI devices, 
since it blacklists all sd* devices. 

blacklist { 

devnode " A sd[a-z]" 

} 
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You can use a devnode entry in the blacklist section of the configuration file to specify individual 
devices to blacklist rather than all devices of a specific type. This is not recommended, however, 
since unless it is statically mapped by udev rules, there is no guarantee that a specific device will have 
the same name on reboot. For example, a device name could change from /dev/sda to /dev/sdb on 
reboot. 

By default, the following devnode entries are compiled in the default blacklist; the devices that these 
entries blacklist do not generally support DM-Multipath. To enable multipathing on any of these 
devices, you would need to specify them in the blacklist_exceptions section of the configuration file, 
as described in Blacklist Exceptions [p. 64] 



blacklist { 

devnode " A (ram | raw | loop | f d | md | dm- | sr | scd | st ) [0-9 ] *" 
devnode " A hd[a-z]" 

} 

4.2.3. Blacklisting By Device Type 

You can specify specific device types in the blacklist section of the configuration file with a device 
section. The following example blacklists all IBM DS4200 and HP devices. 



blacklist { 

device { 

vendor "IBM" 

product "3S42" #DS4200 Product 10 

} 

device { 

vendor "HP" 
product "*" 

} 

} 

4.2.4. Blacklist Exceptions 

You can use the blacklist_exceptions section of the configuration file to enable multipathing on 
devices that have been blacklisted by default. 

For example, if you have a large number of devices and want to multipath only one of them (with the 
WWID of 3600d0230000000000el3955cc3757803), instead of individually blacklisting each of the 
devices except the one you want, you could instead blacklist all of them, and then allow only the one 
you want by adding the following lines to the /etc/multipath.conf file. 



blacklist { 
wwid 

} 
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blacklist_exceptions { 

wwid "3600d0230000000000el3955cc3757803" 

} 

When specifying devices in the blacklist_exceptions section of the configuration file, you must 
specify the exceptions in the same way they were specified in the blacklist. For example, a WWID 
exception will not apply to devices specified by a devnode blacklist entry, even if the blacklisted 
device is associated with that WWID. Similarly, devnode exceptions apply only to devnode entries, 
and device exceptions apply only to device entries. 

4.3. Configuration File Defaults 

The /etc/multipath.conf configuration file includes a defaults section that sets the 
user_friendly_names parameter to yes, as follows. 

defaults { 

user_f riendly_names yes 

} 

This overwrites the default value of the user_friendly_names parameter. 

The configuration file includes a template of configuration defaults. This section is commented out, as 
follows. 

#defaults { 



# udev_dir /dev 

# polling_interval 5 

# selector "round-robin 0" 

# path_grouping_policy failover 

# getuid_callout " /lib/dev/scsi_id — whitelisted — device=/dev/%n" 

# prio const 



# path_checker directio 

# rr_min_io 1000 

# rr_weight uniform 

# fallback manual 

# no_path_retry fail 

# user_f riendly_names no 
#} 

To overwrite the default value for any of the configuration parameters, you can copy the relevant 
line from this template into the defaults section and uncomment it. For example, to overwrite the 
path_grouping_policy parameter so that it is multibus rather than the default value of failover, copy 
the appropriate line from the template to the initial defaults section of the configuration file, and 
uncomment it, as follows. 

defaults { 

user_f riendly_names yes 
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path_grouping_policy multibus 

} 

Table Multipath Configuration Defaults [p. 66] describes the attributes that are set in the 
defaults section of the multipath. conf configuration file. These values are used by DM-Multipath 
unless they are overwritten by the attributes specified in the devices and multipaths sections of the 
multipath . conf file. 



Table 5.3. Multipath Configuration Defaults 



Attribute 


Description 


polling_interval 


Specifies the interval between two path checks in seconds. For 
properly functioning paths, the interval between checks will 
gradually increase to (4 * polling_interval). The default value is 
5. 


udev_dir 


The directory where udev device nodes are created. The default 
value is /dev. 


multipath_dir 


The directory where the dynamic shared objects are stored. The 
default value is system dependent, commonly /lib/muitipath. 


verbosity 


The default verbosity. Higher values increase the verbosity level. 
Valid levels are between 0 and 6. The default value is 2. 


path_selector 


Specifies the default algorithm to use in determining what path to 
use for the next I/O operation. Possible values include: 

• round-robin 0: Loop through every path in the path group, 
sending the same amount of I/O to each. 

• queue-length 0: Send the next bunch of I/O down the path with 
the least number of outstanding I/O requests. 
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the shortest estimated service time, which is determined by 
dividing the total size of the outstanding I/O to each path by its 
relative throughput. 

The default value is round-robin 0. 


path_grouping_policy 


Specifies the default path grouping policy to apply to unspecified 
multipaths. Possible values include: 

• failover = 1 path per priority group 

• multibus = all valid paths in 1 priority group 

• group_by_serial = 1 priority group per detected serial number 

• group_by_prio = 1 priority group per path priority value 

• group_by_node_name = 1 priority group per target node name. 
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Attribute 


Description 




The default value is failover. 


geiuiQ_cauoui 


opecuies ine ueiauii program anu argumenis 10 can oui 10 ouiain a 
unique path identifier. An absolute path is required. 

The default value is /lib/udev/scsi_id --whitelisted --device=/dev/ 
%n. 


prio 


Specifies the default function to call to obtain a path priority value. 
For example, the ALUA bits in SPC-3 provide an exploitable prio 
value. Possible values include: 

• const: Set a priority of 1 to all paths. 

• emc: Generate the path priority for EMC arrays. 

• alua: Generate the path priority based on the SCSI-3 ALUA 
settings. 

• netapp: Generate the path priority for NetApp arrays. 

• rdac: Generate the path priority for LSI/Engenio RDAC 
controller. 

• hp_sw: Generate the path priority for Compaq/HP controller in 
active/standby mode. 

• hds: Generate the path priority for Hitachi HDS Modular 
storage arrays. 

The default value is const. 


prio_args 


The arguments string passed to the prio function Most prio 
functions do not need arguments. The datacore prioritizer need 
one. Example, "timeout=1000 preferredsds=foo" . The default 
value is (null) " " . 


features 


The extra features of multipath devices. The only existing feature 
is queue_if_no_path, which is the same as setting no_path_retry 

to queue. For information on issues that may arise when using this 
feature, see Section, "Issues with queue _if_no _j>ath feature" . 


path_checker 


Specifies the default method used to determine the state of the 
paths. Possible values include: 

• readsectorO: Read the first sector of the device. 

• tur: Issue a TEST UNIT READY to the device. 

• emc_clariion: Query the EMC Clariion specific EVPD page 
OxCO to determine the path. 

• hp_sw: Check the path state for HP storage arrays with Active/ 
Standby firmware. 



67 



DM-Multipath 



Attribute 


Description 




• rdac: Check the path status for LSI/Engenio RDAC storage 
controller. 

• directio: Read the first sector with direct I/O. 
The default value is directio. 


fallback 


Manages path group fallback. 

• A value of immediate specifies immediate fallback to the 
highest priority path group that contains active paths. 

• A value of manual specifies that there should not be immediate 
fallback but that fallback can happen only with operator 
intervention. 

• A numeric value greater than zero specifies deferred fallback, 
expressed in seconds. 

The default value is manual. 


rr_min_io 


Specifies the number of I/O requests to route to a path before 
switching to the next path in the current path group. 

The default value is 1000. 


rr_weight 


If set to priorities, then instead of sending rr_min_io requests 
to a path before calling path_selector to choose the next path, 
me nuniDer or requests 10 send is determined oy rr_iniii_iu nines 
the path's priority, as determined by the prio function. If set to 
uniform, all path weights are equal. 

The default value is uniform. 


no_path_retry 


A numeric value for this attribute specifies the number of times 
the system should attempt to use a failed path before disabling 
queueing. /\ vaiue oi laii indicates imineuidie lanure, wimoui 
queueing. A value of queue indicates that queueing should not 
stop until the path is fixed. 

The default value is o . 


user_friendly_names 


If set to yes, specifies that the system should use the /etc/ 
multipath/bindings file to assign a persistent and unique alias 
to the multipath, in the form of mpathn. If set to no, specifies that 
the system should use the WWID as the alias for the multipath. 
In either case, what is specified here will be overridden by any 
device- specific aliases you specify in the multipaths section of the 
configuration file. 
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Attribute 


Description 




The default value is no. 


queue_without_daemon 


If set to no, the multipathd daemon will disable queueing for all 
devices when it is shut down. 

The default value is yes. 


flush_on_last_del 


If set to yes, then multipath will disable queueing when the last 
path to a device has been deleted. 

The default value is no. 


max_fds 


Sets the maximum number of open file descriptors that can 
be opened by multipath and the multipathd daemon. This is 
equivalent to the ulimit -n command. A value of max will set this 
to the system limit from /proc/sys/f s/nr_open. If this is not set, 
the maximum number of open file descriptors is taken from the 
calling process; it is usually 1024. To be safe, this should be set to 
the maximum number of paths plus 32, if that number is greater 
than 1024. 


CIlcCKCI lllllcl 


i ne umeoui 10 use lor pain cnecKers inai issue ov^oi commands 
with an explicit timeout, in seconds. 

The default value is taken from /sys/block/sdx/device/ 
timeout, which is 30 seconds as of 12.04 LTS 


fast_io_fail_tmo 


The number of seconds the SCSI layer will wait after a problem 
lias ueeii ueiecieu on an lenioie poll ueioie laiiing lo 
devices on that remote port. This value should be smaller than the 
value of dev_loss_tmo. Setting this to off will disable the timeout. 

The default value is determined by the OS . 


dev_loss_tmo 


The number of seconds the SCSI layer will wait after a problem 
has been detected on an FC remote port before removing it from 
the system. Setting this to infinity will set this to 2147483647 
seconds, or 68 years. The default value is determined by the OS. 



4.4. Configuration File Multipath Attributes 



Table Multipath Attributes [p. 70] shows the attributes that you can set in the multipaths section 
of the multipath. conf configuration file for each specific multipath device. These attributes apply 
only to the one specified multipath. These defaults are used by DM-Multipath and override attributes 
set in the defaults and devices sections of the multipath .conf file. 



69 



DM-Multipath 



Table 5.4. Multipath Attributes 



Attribute 


Description 


wwid 


Specifies the WWID of the multipath device to which the multipath 

attributes apply. This parameter is mandatory for this section of the 
multipath . conf file. 


alias 


Specifies the symbolic name for the multipath device to which the 
multipath attributes apply. If you are using user_friendly_names, do not 

set this value to mpathn; this may conflict with an automatically assigned 
user friendly name and give you incorrect device node names. 



In addition, the following parameters may be overridden in this multipath section 

• path_grouping_policy 

• path_selector 

• fallback 

• prio 

• prio_args 

• no_path_retry 

• rr_min_io 

• rr_weight 

• flush_on_last_del 

The following example shows multipath attributes specified in the configuration file for two specific 
multipath devices. The first device has a WWID of 3600508b4000156d70001200000b0000 and a 
symbolic name of yellow. 

The second multipath device in the example has a WWID of 1DEC 321816758474 and a 

symbolic name of red. In this example, the rr_weight attributes are set to priorities. 



multipaths { 

multipath { 
wwid 
alias 

path_grouping_policy 

path_selector 

fallback 

rr_weight 

no_path_retry 

} 

multipath { 
wwid 
alias 



3600508b4000156d70001200000b0000 

yellow 

multibus 

"round-robin 0" 

manual 

priorities 

5 

1DEC 3218167584 74 

red 
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rr_weight priorities 

} 

} 

4.5. Configuration File Devices 

Table Device Attributes [p. 72] shows the attributes that you can set for each individual storage 
device in the devices section of the multipath.conf configuration file. These attributes are used by 
DM-Multipath unless they are overwritten by the attributes specified in the multipaths section of the 
multipath.conf file for paths that contain the device. These attributes override the attributes set in 
the defaults section of the multipath.conf file. 

Many devices that support multipathing are included by default in a multipath configuration. The 
values for the devices that are supported by default are listed in the multipath . conf . defaults file. 
You probably will not need to modify the values for these devices, but if you do you can overwrite 
the default values by including an entry in the configuration file for the device that overwrites those 
values. You can copy the device configuration defaults from the multipath.conf .annotated. gz or if 
you wish to have a brief config file, multipath.conf . synthetic file for the device and override the 
values that you want to change. 

To add a device to this section of the configuration file that is not configured automatically by default, 
you must set the vendor and product parameters. You can find these values by looking at /sys/block/ 
device_name/device/vendor and /sys/block/device_name/device/model where device_name is the 
device to be multipathed, as in the following example: 

# cat /sys/block/sda/device/vendor 
WINSYS 

# cat /sys/block/sda/device/model 
SF2372 

The additional parameters to specify depend on your specific device. If the device is active/active, 
you will usually not need to set additional parameters. You may want to set path_grouping_policy to 
multibus. Other parameters you may need to set are no jpathjretry and rr_min_io, as described in 
Table Multipath Attributes [p. 70]. 

If the device is active/passive, but it automatically switches paths with I/O to the passive path, 
you need to change the checker function to one that does not send I/O to the path to test if it is 
working (otherwise, your device will keep failing over). This almost always means that you set the 
path_checker to tur; this works for all SCSI devices that support the Test Unit Ready command, 
which most do. 

If the device needs a special command to switch paths, then configuring this device for multipath 
requires a hardware handler kernel module. The current available hardware handler is emc. If this is 
not sufficient for your device, you may not be able to configure the device for multipath. 
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Table 5.5. Device Attributes 



Attribute 


Description 


vendor 


Specifies the vendor name of the storage device to which the device 
attributes apply, for example COMPAQ. 


product 


Specifies the product name of the storage device to which the device 
attributes apply, for example HSV110 (C)COMPAQ. 


revision 


Specifies the product revision identifier of the storage device. 


productjblacklist 


Specifies a regular expression used to blacklist devices by product. 


hardware_handler 


Specifies a module that will be used to perform hardware specific actions 
when switching path groups or handling I/O errors. Possible values 
include: 

• 1 emc: hardware handler for EMC storage arrays 

• 1 alua: hardware handler for SCSI-3 ALUA arrays. 

• 1 hp_sw: hardware handler for Compaq/HP controllers. 

• 1 rdac: hardware handler for the LSI/Engenio RDAC controllers. 



In addition, the following parameters may be overridden in this device section 

• path_grouping_policy 

• getuid_callout 

• path_selector 

• path_checker 

• features 

• fallback 

• prio 

• prio_args 

• no_path_retry 

• rr_min_io 

• rr_weight 

• fast_io_fail_tmo 

• dev_loss_tmo 

• flush_on_last_del 

I Whenever a hardware_handler is specified, it is your responsibility to ensure that the 

appropriate kernel module is loaded to support the specified interface. These modules can 
be found in /lib/modules/ uname -r~ /kernel/drivers/scsi/device_handler/ .The 
requisite module should be integrated into the initrd to ensure the necessary discovery and 
failover-failback capacity is available during boot time. Example, 

72 



DM-Multipath 



# echo scsi_dh_alua » /etc/initramf s-tools/modules ## append module to file 

# update-initramf s -u -k all 

The following example shows a device entry in the multipath configuration file. 

#devices { 

# device { 

# vendor "COMPAQ " 

# product "MSA1000 

# path_grouping_policy multibus 

# path_checker tur 

# rr_weight priorities 

# } 
#} 

The spacing reserved in the vendor, product, and revision fields are significant as multipath is 
performing a direct match against these attributes, whose format is defined by the SCSI specification, 
specifically the Standard INQUIRY 2 command. When quotes are used, the vendor, product, and 
revision fields will be interpreted strictly according to the spec. Regular expressions may be integrated 
into the quoted strings. Should a field be defined without the requisite spacing, multipath will 
copy the string into the properly sized buffer and pad with the appropriate number of spaces. The 
specification expects the entire field to be populated by printable characters or spaces, as seen in the 
example above 

# vendor: 8 characters 

# product: 16 characters 

# revision: 4 characters 

To create a more robust configuration file, regular expressions can also be used. Operators include A 
$[].*?+. Examples of functional regular expressions can be found by examining the live multipath 
database and multipath. conf example files found in /usr/share/doc/multipath-tools/examples: 

# echo 'show config' | multipathd -k 



http://en.wikipedia.org/wiki/SCSI_Inquiry_Command 
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5. DM-Multipath Administration and Troubleshooting 

5.1 . Resizing an Online Multipath Device 

If you need to resize an online multipath device, use the following procedure 

1 . Resize your physical device. This is storage platform specific. 

2. Use the following command to find the paths to the LUN: 

# multipath -1 

3. Resize your paths. For SCSI devices, writing 1 to the rescan file for the device causes the SCSI 
driver to rescan, as in the following command: 

# echo 1 > /sys/block/device_name/device/rescan 

4. Resize your multipath device by running the multipathd resize command: 

# multipathd -k 'resize map mpatha' 

5. Resize the file system (assuming no LVM or DOS partitions are used): 

# resize2fs /dev/mapper /mpatha 

5.2. Moving root File Systems from a Single Path Device to a Multipath 
Device 

This is dramatically simplified by the use of UUIDs to identify devices as an intrinsic label. Simply 
install multipath-tools-boot and reboot. This will rebuild the initial ramdisk and afford multipath the 
opportunity to build it's paths before the root file system is mounted by UUID. 

Whenever multipath. conf is updated, so should the initrd by executing update-initramfs 
-u -k all. The reason being is multipath . conf is copied to the ramdisk and is integral to 
determining the available devices for grouping via it's blacklist and device sections. 

5.3. Moving swap File Systems from a Single Path Device to a Multipath 
Device 

The procedure is exactly the same as illustrated in the previous section called Moving root File 
Systems from a Single Path to a Multipath Device. 

5.4. The Multipath Daemon 

If you find you have trouble implementing a multipath configuration, you should ensure the multipath 
daemon is running as described in "Setting up DM-Multipath" . The multipathd daemon must be 
running in order to use multipathd devices. Also see section Troubleshooting with the multipathd 
interactive console concerning interacting with multipathd as a debugging aid. 
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5 .5 . Issues with queue if no path 

If features "1 queue_if_no_path" is specified in the /etc/muitipath.conf file, then any process 
that uses I/O will hang until one or more paths are restored. To avoid this, set the no _path_retry N 
parameter in the /etc/multipath.conf . 

When you set the no_path_retry parameter, remove the features "1 queue_if_no_path " option 
from the /etc/multipath.conf file as well. If, however, you are using a multipathed device for 
which the features " l queue_if_no_path" option is set as a compiled in default, as it is for many 
SAN devices, you must add features " o " to override this default. You can do this by copying the 
existing devices section, and just that section (not the entire file), from /usr/share/doc/muitipath- 
tools/examples/multipath.conf .annotated. gz into /etc/multipath.conf and editing to suit your 

needs. 

If you need to use the features " l queue_if_no_path" option and you experience the issue noted 
here, use the dmsetup command to edit the policy at runtime for a particular LUN (that is, for which 
all the paths are unavailable). For example, if you want to change the policy on the multipath device 
mpathc from "queue_if_no_path" to "f ail_if_no_path" , execute the following command. 

# dmsetup message mpathc 0 "f ail_if_no_path" 



5.6. Multipath Command Output 

When you create, modify, or list a multipath device, you get a printout of the current device setup. 
The format is as follows. For each multipath device: 

action_if _any : alias ( wwid_if _dif f erent_f rom_alias ) dm_device_name_if _known vendor , product 
size=size features= ' features ' hwhandler= ' hardware_handler ' wp=write_permission_if _known 

For each path group: 

-+- policy= ' scheduling_policy ' prio=prio_if _known 
status=path_group_status_if _known 

For each path: 

host : channel : id : lun devnode major: minor dm_status_if _known path_status 
online_status 

For example, the output of a multipath command might appear as follows: 

3600d0230000000000el3955cc3757800 dm-1 WINSYS , SF2372 

size=269G f eatures= ' 0 ' hwhandler= ' 0 1 wp=rw 

| -+- policy= ' round-robin 0' prio=l status=active 

| 6:0:0:0 sdb 8:16 active ready running 

"-+- policy= ' round-robin 0' prio=l status=enabled 




You must specify the mpathN alias rather than the path 
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"- 7:0:0:0 sdf 8:80 active ready running 

If the path is up and ready for I/O, the status of the path is ready or ghost. If the path is down, the 
status is faulty or shaky. The path status is updated periodically by the multipathd daemon based on 
the polling interval defined in the /etc/multipath.conf file. 

The dm status is similar to the path status, but from the kernel's point of view. The dm status has 
two states: failed, which is analogous to faulty, and active which covers all other path states. 
Occasionally, the path state and the dm state of a device will temporarily not agree. 

The possible values for online_status are running and offline. A status of offline means that the 
SCSI device has been disabled. 

When a multipath device is being created or modified , the path group status, the dm device 
name, the write permissions, and the dm status are not known. Also, the features are not 
always correct 

5 .7 . Multipath Queries with multipath Command 

You can use the -1 and -11 options of the multipath command to display the current multipath 
configuration. The -1 option displays multipath topology gathered from information in sysfs and the 
device mapper. The -11 option displays the information the -I displays in addition to all other available 
components of the system. 

When displaying the multipath configuration, there are three verbosity levels you can specify with 
the -v option of the multipath command. Specifying -vO yields no output. Specifying -vl outputs 
the created or updated multipath names only, which you can then feed to other tools such as kpartx. 
Specifying -v2 prints all detected paths, multipaths, and device maps. 

The default verbosity level of multipath is 2 and can be globally modified by defining the 
verbosity attribute in the defaults section of multipath . conf . 

The following example shows the output of a multipath -1 command. 

# multipath -1 
3600d0230000000000el3955cc3757800 dm-1 WINSYS , SF2372 
size=269G f eatures= ' 0 ' hwhandler= ' 0 ' wp=rw 

| -+- policy= ' round-robin 0' prio=l status=active 
| "- 6:0:0:0 sdb 8:16 active ready running 
"-+- policy= ' round-robin 0' prio=l status=enabled 
"- 7:0:0:0 sdf 8:80 active ready running 

The following example shows the output of a multipath -11 command. 

# multipath -11 
3600d0230000000000el3955cc3757801 dm- 10 WINSYS , SF2372 
size=269G f eatures= ' 0 ' hwhandler= ' 0 ' wp=rw 

| -+- policy= ' round-robin 0' prio=l status=enabled 
| 19:0:0:1 sdc 8:32 active ready running 
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"-+- policy= ' round-robin 0' prio=l status=enabled 
18:0:0:1 sdh 8:112 active ready running 
3600d0230000000000el3955cc3757803 dm-2 WINSYS , SF2372 
size=125G f eatures= ' 0 ' hwhandler= ' 0 ' wp=rw 
"-+- policy= ' round-robin 0' prio=l status=active 
|- 19:0:0:3 sde 8:64 active ready running 

18:0:0:3 sdj 8:144 active ready running 

5.8. Multipath Command Options 

Table Useful multipath Command Options [p. 77] describes some options of the multipath 
command that you might find useful. 



Table 5.6. Useful multipath Command Options 



Option 


Description 


-1 


Display the current multipath configuration gathered from sysfs and 
the device mapper. 


-11 


Display the current multipath configuration gathered from sysfs, the 
device mapper, and all other available components on the system. 


-f device 


Remove the named multipath device. 


-F 


Remove all unused multipath devices. 


5.9. Determining Device Mapper Entries with dmsetup Command 



You can use the dmsetup command to find out which device mapper entries match the multipathed 

devices. 



The following command displays all the device mapper devices and their major and minor numbers. 
The minor numbers determine the name of the dm device. For example, a minor number of 3 
corresponds to the multipathed device /dev/dm-3. 



# dmsetup Is 
mpathd (253, 4) 
mpathepl (253, 12) 

mpathfpl (253, 11) 

mpathb (253, 3) 
mpathgpl (253, 14) 

mpathhpl (253, 13) 

mpatha (253, 2) 
mpathh (253, 9) 
mpathg (253, 8) 

VolGroupOO-LogVolOl (253, 1) 

mpathf (253, 7) 

VolGroupOO-LogVolOO (253, 0) 

mpathe (253, 6) 
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mpathbpl (253, 10) 

mpathd (253, 5) 

5.10. Troubleshooting with the multipathd interactive console 

The multipathd -k command is an interactive interface to the multipathd daemon. Entering this 
command brings up an interactive multipath console. After entering this command, you can enter help 
to get a list of available commands, you can enter a interactive command, or you can enter CTRL-D 
to quit. 

The multipathd interactive console can be used to troubleshoot problems you may be having with 
your system. For example, the following command sequence displays the multipath configuration, 
including the defaults, before exiting the console. See the IBM article "Tricks with Multipathd" 3 for 
more examples. 

# multipathd -k 

> > show config 

> > CTRL-D 

The following command sequence ensures that multipath has picked up any changes to the 
multipath .conf, 

# multipathd -k 

> > reconfigure 

> > CTRL-D 

Use the following command sequence to ensure that the path checker is working properly. 

# multipathd -k 

> > show paths 

> > CTRL-D 

Commands can also be streamed into multipathd using stdin like so: 

# echo 'show config' | multipathd -k 



http://www-01. ibm.com/support/docview .wss?uid=isg3T101 1985 
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Chapter 6. Remote Administration 

There are many ways to remotely administer a Linux server. This chapter will cover three of the most 
popular applications OpenSSH, Puppet, and Zentyal. 
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1. QpenSSH Server 

1.1. Introduction 

This section of the Ubuntu Server Guide introduces a powerful collection of tools for the remote 
control of, and transfer of data between, networked computers called OpenSSH. You will also learn 
about some of the configuration settings possible with the OpenSSH server application and how to 
change them on your Ubuntu system. 

OpenSSH is a freely available version of the Secure Shell (SSH) protocol family of tools for remotely 
controlling, or transferring files between, computers. Traditional tools used to accomplish these 
functions, such as telnet or rep, are insecure and transmit the user's password in cleartext when used. 
OpenSSH provides a server daemon and client tools to facilitate secure, encrypted remote control and 
file transfer operations, effectively replacing the legacy tools. 

The OpenSSH server component, sshd, listens continuously for client connections from any of the 
client tools. When a connection request occurs, sshd sets up the correct connection depending on the 
type of client tool connecting. For example, if the remote computer is connecting with the ssh client 
application, the OpenSSH server sets up a remote control session after authentication. If a remote user 
connects to an OpenSSH server with scp, the OpenSSH server daemon initiates a secure copy of files 
between the server and client after authentication. OpenSSH can use many authentication methods, 
including plain password, public key, and Kerberos tickets. 

1.2. Installation 

Installation of the OpenSSH client and server applications is simple. To install the OpenSSH client 
applications on your Ubuntu system, use this command at a terminal prompt: 

sudo apt-get install openssh-client 

To install the OpenSSH server application, and related support files, use this command at a terminal 
prompt: 

sudo apt-get install openssh-server 

The openssh-server package can also be selected to install during the Server Edition installation 
process. 

1 .3 . Configuration 

You may configure the default behavior of the OpenSSH server application, sshd, by editing the file 
/etc/ssh/sshd_conf ig. For information about the configuration directives used in this file, you may 
view the appropriate manual page with the following command, issued at a terminal prompt: 

man sshd_config 
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There are many directives in the sshd configuration file controlling such things as communication 
settings, and authentication modes. The following are examples of configuration directives that can be 
changed by editing the /etc/ssh/sshd_conf ig file. 




Prior to editing the configuration file, you should make a copy of the original file and protect 
it from writing so you will have the original settings as a reference and to reuse as necessary. 



Copy the /etc/ssh/sshd_conf ig file and protect it from writing with the following 
commands, issued at a terminal prompt: 

sudo cp /etc/ssh/sshd_conf ig /etc/ssh/sshd_conf ig. original 
sudo chmod a-w /etc/ssh/sshdconf ig . original 

The following are examples of configuration directives you may change: 

• To set your OpenSSH to listen on TCP port 2222 instead of the default TCP port 22, change the 
Port directive as such: 

Port 2222 

• To have sshd allow public key-based login credentials, simply add or modify the line: 
Pubkey Authentication yes 

If the line is already present, then ensure it is not commented out. 

• To make your OpenSSH server display the contents of the /etc/issue, net file as a pre-login 
banner, simply add or modify the line: 

Banner /etc/issue .net 

In the /etc/ssh/sshd conf ig file. 

After making changes to the /etc/ssh/sshd conf ig file, save the file, and restart the sshd server 
application to effect the changes using the following command at a terminal prompt: 

sudo service ssh restart 




Many other configuration directives for sshd are available to change the server application's 
behavior to fit your needs. Be advised, however, if your only method of access to a server 



is ssh, and you make a mistake in configuring sshd via the /etc/ssh/sshd_conf ig file, you 
may find you are locked out of the server upon restarting it. Additionally, if an incorrect 
configuration directive is supplied, the sshd server may refuse to start, so be extra careful 
when editing this file on a remote server. 

1.4. SSH Keys 

SSH keys allow authentication between two hosts without the need of a password. SSH key 
authentication uses two keys, a private key and a public key. 
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To generate the keys, from a terminal prompt enter: 



ssh-keygen -t dsa 

This will generate the keys using the Digital Signature Algorithm (DSA) method. During the process 
you will be prompted for a password. Simply hit Enter when prompted to create the key. 

By default the public key is saved in the file -/ . ssh/id_dsa.pub, while -/ . ssh/id_dsa is the private 
key. Now copy the id_dsa.pub file to the remote host and append it to ~/.ssh/authorized_keys by 
entering: 



ssh-copy-id username@remotehost 

Finally, double check the permissions on the authorizedjceys file, only the authenticated user 
should have read and write permissions. If the permissions are not correct change them by: 



chmod 600 . ssh/authorized_keys 

You should now be able to SSH to the host without being prompted for a password. 

1 .5 . References 

• Ubuntu Wiki SSH 1 page. 

• OpenSSH Website 2 

• Advanced OpenSSH Wiki Page 3 



https://help.ubuntu.com/community/SSH 

http://www.openssh.org/ 

https://wiki.ubuntu.com/AdvancedOpenSSH 
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2. Pupp et 

Puppet is a cross platform framework enabling system administrators to perform common tasks using 
code. The code can do a variety of tasks from installing new software, to checking file permissions, 
or updating user accounts. Puppet is great not only during the initial installation of a system, but also 
throughout the system's entire life cycle. In most circumstances puppet will be used in a client/server 
configuration. 

This section will cover installing and configuring Puppet in a client/server configuration. This simple 
example will demonstrate how to install Apache using Puppet. 

2.1. Preconfiguration 

Prior to configuring puppet you may want to add a DNS CNAME record for puppet .example .com, 
where example.com is your domain. By default Puppet clients check DNS for puppet.example.com as 
the puppet server name, or Puppet Master. See Chapter 8, Domain Name Service (DNS) [p. 138] 
for more DNS details. 

If you do not wish to use DNS, you can add entries to the server and client /etc/hosts file. For 
example, in the Puppet server's /etc/hosts file add: 

127.0.0.1 localhost . localdomain localhost puppet 
192.168.1.17 puppetclient.example.com puppetclient 

On each Puppet client, add an entry for the server: 

192.168.1.16 puppetmaster.example.com puppetmaster puppet 




Replace the example IP addresses and domain names above with your actual server and 
client addresses and domain names. 



2.2. Installation 

To install Puppet, in a terminal on the server enter: 

sudo apt-get install puppetmaster 

On the client machine, or machines, enter: 

sudo apt-get install puppet 

2.3. Configuration 

Create a folder path for the apache2 class: 
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sudo mkdir -p /etc/puppet/modules/apache2/manif ests 

Now setup some resources for apache2. Create a file /etc/puppet/moduies/apache2/manif ests/ 
init .pp containing the following: 



class apache2 { 

package { ' apache2 ' : 
ensure => installed, 

} 

service { ' apache2 ' : 
ensure => true, 
enable => true, 
require => Package [ ' apache2 ' ] , 

} 

} 

Next, create a node file /etc/puppet/manifests/site. pp with: 



node 'puppetclient.example.com' { 
include apache2 

} 

Replace puppetclient.example.com with your actual Puppet client's host name. 



The final step for this simple Puppet server is to restart the daemon: 
sudo service puppetmaster restart 

Now everything is configured on the Puppet server, it is time to configure the client. 

First, configure the Puppet agent daemon to start. Edit /etc/default/puppet, changing START to 
yes: 

START=yes 

Then start the service: 

sudo service puppet start 

View the client cert fingerprint 

sudo puppet agent --fingerprint 

Back on the Puppet server, view pending certificate signing requests: 
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sudo puppet cert list 

On the Puppet server, verify the fingerprint of the client and sign puppetclient's cert: 
sudo puppet cert sign puppetclient.example.com 

On the Puppet client, run the puppet agent manually in the foreground. This step isn't strictly speaking 
necessary, but it is the best way to test and debug the puppet service. 

sudo puppet agent --test 

Check /var/iog/syslog on both hosts for any errors with the configuration. If all goes well the 
apache2 package and it's dependencies will be installed on the Puppet client. 




This example is very simple, and does not highlight many of Puppet's features and benefits. 
For more information see Section 2.4, "Resources" [p. 85]. 



2.4. Resources 



• See the Official Puppet Documentation web site. 

• See the Puppet forge 5 , online repository of puppet modules. 

• Also see Pro Puppet 6 . 



http://docs.puppetlabs.com/ 
^ http://forge.puppetlabs.com/ 
6 http://www.apress.com/9781430230571 
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3. Zentyal 

Zentyal is a Linux small business server, that can be configured as a Gateway, Infrastructure 
Manager, Unified Threat Manager, Office Server, Unified Communication Server or a combination 
of them. All network services managed by Zentyal are tightly integrated, automating most tasks. This 
helps to avoid errors in the network configuration and administration and allows to save time. Zentyal 
is open source, released under the GNU General Public License (GPL) and runs on top of Ubuntu 
GNU/Linux. 

Zentyal consists of a series of packages (usually one for each module) that provide a web interface to 
configure the different servers or services. The configuration is stored on a key-value Redis database 
but users, groups and domains related configuration is on OpenLDAP . When you configure any of 
the available parameters through the web interface, final configuration files are overwritten using the 
configuration templates provided by the modules. The main advantages of using Zentyal are: unified, 
graphical user interface to configure all network services and high, out-of-the-box integration between 
them. 

3.1. Installation 

Zentyal 2.3 is available on Ubuntu 12.04 Universe repository. The modules available are: 

• zentyal-core & zentyal-common: the core of the Zentyal interface and the common libraries of the 
framework. Also include the logs and events modules that give the administrator an interface to 
view the logs and generate events from them. 

• zentyal-network: manages the configuration of the network. From the interfaces (supporting static 
IP, DHCP, VLAN, bridges or PPPoE), to multiple gateways when having more than one Internet 
connection, load balancing and advanced routing, static routes or dynamic DNS. 

• zentyal-objects & zentyal-services: provide an abstraction level for network addresses (e.g. LAN 
instead of 192.168.1.0/24) and ports named as services (e.g. HTTP instead of 80/TCP). 

• zentyal-firewall: configures the iptables rules to block forbiden connections, NAT and port 
redirections. 

• zentyal-ntp: installs the NTP daemon to keep server on time and allow network clients to 
synchronize their clocks against the server. 

• zentyal-dhcp: configures ISC DHCP server supporting network ranges, static leases and other 
advanced options like NTP, WINS, dynamic DNS updates and network boot with PXE. 

• zentyal-dns: brings ISC Bind9 DNS server into your server for caching local queries as a forwarder 
or as an authoritative server for the configured domains. Allows to configure A, CNAME, MX, NS, 
TXT and SRV records. 

• zentyal-ca: integrates the management of a Certification Authority within Zentyal so users can use 
certificates to authenticate against the services, like with OpenVPN. 

• zentyal-openvpn: allows to configure multiple VPN servers and clients using OpenVPN with 
dynamic routing configuration using Quagga. 
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• zentyal-users: provides an interface to configure and manage users and groups on OpenLDAP. 
Other services on Zentyal are authenticated against LDAP having a centralized users and groups 
management. It is also possible to synchronize users, passwords and groups from a Microsoft 
Active Directory domain. 

• zentyal-squid: configures Squid and Dansguardian for speeding up browsing thanks to the caching 
capabilities and content filtering. 

• zentyal-samba: allows Samba configuration and integration with existing LDAP. From the same 
interface you can define password policies, create shared resources and assign permissions. 

• zentyal-printers: integrates CUPS with Samba and allows not only to configure the printers but also 
give them permissions based on LDAP users and groups. 

To install Zentyal, in a terminal on the server enter (where <zentyal-module> is any of the modules 
from the previous list): 



sudo apt-get install <zentyal-module> 

Zentyal publishes one major stable release once a year (in September) based on latest 
Ubuntu LTS release. Stable releases always have even minor numbers (e.g. 2.2, 3.0) and 
beta releases have odd minor numbers (e.g. 2.1, 2.3). Ubuntu 12.04 comes with Zentyal 
2.3 packages. If you want to upgrade to a new stable release published after the release 
of Ubuntu 12.04 you can use Zentyal Team PPA 7 . Upgrading to newer stable releases can 
provide you minor bugfixes not backported to 2.3 in Precise and newer features. 

If you need more information on how to add packages from a PPA see Add a Personal 
Package Archive (PPA) . 

Not present on Ubuntu Universe repositories, but on Zentyal Team PPA 9 you will find these 
other modules: 

• zentyal-antivirus: integrates ClamAV antivirus with other modules like the proxy, file 
sharing or mailfilter. 

• zentyal-asterisk: configures Asterisk to provide a simple PBX with LDAP based 
authentication. 

• zentyaLbwmonitor: allows to monitor bandwith usage of your LAN clients. 

• zentyal-captiveportal: integrates a captive portal with the firewall and LDAP users and 
groups. 

• zentyal-ebackup: allows to make scheduled backups of your server using the popular 
duplicity backup tool. 

• zentyal-ftp: configures a FTP server with LDAP based authentication. 



7 



https ://launchpad.net/~zentyal/ 

https://help.ubuntu.com/14.04/ubuntu-help/addremove-ppa.html 



Q 

https ://launchpad.net/~zentyal/ 
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• zentyal-ids: integrates a network intrusion detection system. 

• zentyal-ipsec: allows to configure IPsec tunnels using OpenSwan. 

• zentyal-jabber: integrates ejabberd XMPP server with LDAP users and groups. 

• zentyal-thinclients: a LTSP based thin clients solution. 

• zentyal-mail: a full mail stack including Postfix and Dovecot with LDAP backend. 

• zentyal-mailfilter: configures amavisd with mail stack to filter spam and attached virus. 

• zentyal-monitor: integrates collectd to monitor server performance and running services. 

• zentyal-pptp: configures a PPTP VPN server. 

• zentyal-radius: integrates FreeRADIUS with LDAP users and groups. 

• zentyal-software: simple interface to manage installed Zentyal modules and system 
updates. 

• zentyal-trafficshaping: configures traffic limiting rules to do bandwidth throttling and 
improve latency. 

• zentyal-usercorner: allows users to edit their own LDAP attributes using a web browser. 

• zentyal-virt: simple interface to create and manage virtual machines based on libvirt. 

• zentyal-webmail: allows to access your mail using the popular Roundcube webmail. 

• zentyal-webserver: configures Apache webserver to host different sites on your machine. 

• zentyal-zarafa: integrates Zarafa groupware suite with Zentyal mail stack and LDAP. 

3.2. First steps 

Any system account belonging to the sudo group is allowed to log into Zentyal web interface. If you 
are using the user created during the installation, this should be in the sudo group by default. 




If you need to add another user to the sudo group, just execute: 



sudo adduser username sudo 

To access Zentyal web interface, browse into https://localhost/ (or the IP of your remote server). As 
Zentyal creates its own self-signed SSL certificate, you will have to accept a security exception on 
your browser. 

Once logged in you will see the dashboard with an overview of your server. To configure any of the 
features of your installed modules, go to the different sections on the left menu. When you make any 
changes, on the upper right corner appears a red Save changes button that you must click to save all 
configuration changes. To apply these configuration changes in your server, the module needs to be 
enabled first, you can do so from the Module Status entry on the left menu. Every time you enable a 
module, a pop-up will appear asking for a confirmation to perform the necessary actions and changes 
on your server and configuration files. 
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l%— I If you need to customize any configuration file or run certain actions (scripts or commands) 
to configure features not available on Zentyal place the custom configuration file templates 
on /etc/zentyal/stubs/<module>/ and the hooks on /etc/zentyal/hooks/<module>.<action>. 

3 .3 . References 

Zentyal Official Documentation 10 page. 

See also Zentyal Community Documentation 11 page. 

And don't forget to visit the forum 12 for community support, feedback, feature requests, etc. 



http://doc.zentyal.org/ 

http://trac.zentyal.org/wiki/Documentation 

http://forum.zentyal.org/ 
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1. OpenLDAP Server 

The Lightweight Directory Access Protocol, or LDAP, is a protocol for querying and modifying 
a X.500-based directory service running over TCP/IP. The current LDAP version is LDAPv3, as 
defined in RFC4510 1 , and the LDAP implementation used in Ubuntu is OpenLDAP, currently at 
version 2.4.25 (Oneiric). 

So this protocol accesses LDAP directories. Here are some key concepts and terms: 

• A LDAP directory is a tree of data entries that is hierarchical in nature and is called the Directory 
Information Tree (DIT). 

• An entry consists of a set of attributes. 

• An attribute has a type (a name/description) and one or more values. 

• Every attribute must be defined in at least one objectClass. 

• Attributes and objectclasses are defined in schemas (an objectclass is actually considered as a 
special kind of attribute) . 

• Each entry has a unique identifier: it's Distinguished Name (DN or dn). This consists of it's Relative 
Distinguished Name (RDN) followed by the parent entry's DN. 

• The entry's DN is not an attribute. It is not considered part of the entry itself. 

The terms object, container, and node have certain connotations but they all essentially 
mean the same thing as entry, the technically correct term. 

For example, below we have a single entry consisting of 11 attributes. It's DN is "cn=John 
Doe,dc=example,dc=com"; it's RDN is "cn=John Doe"; and it's parent DN is "dc=example,dc=com". 

dn: cn=John Doe , dc=example , dc=com 
cn: John Doe 
givenName : John 
sn: Doe 

telephoneNumber : +1 888 555 6789 
telephoneNumber : +1 888 555 1232 
mail: john@example.com 

manager: cn=Larry Smith , dc=example , dc=com 
objectClass: inetOrgPerson 
objectClass : organizationalPerson 
objectClass: person 
objectClass: top 

The above entry is in LDIF format (LDAP Data Interchange Format) . Any information that you feed 
into your DIT must also be in such a format. It is defined in RFC2849 1 . 

Although this guide will describe how to use it for central authentication, LDAP is good for anything 
that involves a large number of access requests to a mostly-read, attribute-based (name:value) 

1 http://tools.ietf .org/html/rfc45 10 

2 http://tools.ietf.org/html/rfc2849 
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backend. Examples include an address book, a list of email addresses, and a mail server's 
configuration. 

1.1. Installation 

Install the OpenLDAP server daemon and the traditional LDAP management utilities. These are 
found in packages slapd and ldap-utils respectively. 

The installation of slapd will create a working configuration. In particular, it will create a database 
instance that you can use to store your data. However, the suffix (or base DN) of this instance will be 
determined from the domain name of the localhost. If you want something different, edit /etc/hosts 
and replace the domain name with one that will give you the suffix you desire. For instance, if you 
want a suffix of dc=example,dc=com then your file would have a line similar to this: 



12 7.0.1.1 hostname.example.com hostname 

You can revert the change after package installation. 
* — I This guide will use a database suffix of dc= example, dc= com. 



Proceed with the install: 



sudo apt-get install slapd ldap-utils 

Since Ubuntu 8.10 slapd is designed to be configured within slapd itself by dedicating a separate 
DIT for that purpose. This allows one to dynamically configure slapd without the need to restart the 
service. This configuration database consists of a collection of text-based LDIF files located under / 
etc/ldap/slapd.d. This way of working is known by several names: the slapd-config method, the 
RTC method (Real Time Configuration), or the cn=config method. You can still use the traditional 
flat-file method (slapd.conf) but it's not recommended; the functionality will be eventually phased out. 




Ubuntu now uses the slapd-config method for slapd configuration and this guide reflects 
that. 



During the install you were prompted to define administrative credentials. These are LDAP- 
based credentials for the rootDN of your database instance. By default, this user's DN is 
cn= admin, dc= example ,dc=com. Also by default, there is no administrative account created for the 
slapd-config database and you will therefore need to authenticate externally to LDAP in order to 
access it. We will see how to do this later on. 

Some classical schemas (cosine, nis, inetorgperson) come built-in with slapd nowadays. There is also 
an included "core" schema, a pre-requisite for any schema to work. 
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1.2. Post-install Inspection 

The installation process set up 2 DITs. One for slapd-config and one for your own data 
(dc=example,dc=com). Let's take a look. 

• This is what the slapd-config database/DIT looks like. Recall that this database is LDIF-based and 
lives under /etc/ldap/slapd.d: 



/etc/ldap/slapd . d/ 
/etc/ldap/slapd . d/cn=conf ig 

/etc/ldap/slapd . d/cn=conf ig/cn=module{ 0 } . ldif 
/etc/ldap/slapd . d/cn=conf ig/cn=schema 

/etc/ldap/slapd . d/cn=conf ig/cn=schema/cn={ 0 }core .ldif 
/etc/ldap/slapd . d/cn=conf ig/cn=schema/cn={ 1 } cosine .ldif 
/etc/ldap/slapd . d/cn=conf ig/cn=schema/cn={2 }nis .ldif 
/etc/ldap/slapd . d/cn=conf ig/cn=schema/cn={3 }inetorgperson .ldif 
/etc/ldap/slapd . d/cn=conf ig/cn=schema .ldif 
/etc/ldap/slapd . d/cn=conf ig/olcBackend={ 0 }hdb .ldif 
/etc/ldap/slapd . d/cn=conf ig/olcDatabase={ 0 }conf ig . ldif 
/etc/ldap/slapd . d/cn=conf ig/olcDatabase={-l }f rontend .ldif 
/etc/ldap/slapd . d/cn=conf ig/olcDatabase={ 1 }hdb .ldif 
/etc/ldap/slapd . d/cn=conf ig .ldif 



Do not edit the slapd-config database directly. Make changes via the LDAP protocol 
(utilities). 



This is what the slapd-config DIT looks like via the LDAP protocol: 

sudo ldapsearch -Q -LLL -Y EXTERNAL -H ldapi:/// -b cn=config dn 

dn: cn=config 

dn: cn=module{ 0 } , cn=conf ig 

dn: cn=schema, cn=conf ig 

dn : cn={ 0 }core , cn=schema, cn=conf ig 

dn : cn={ 1 } cosine , cn=schema, cn=conf ig 

dn: cn={2 }nis , cn=schema, cn=conf ig 

dn : cn={3 }inetorgperson, cn=schema, cn=conf ig 

dn: olcBackend={ 0 }hdb, cn=conf ig 

dn : olcDatabase={-l }f rontend, cn=conf ig 

dn : olcDatabase={ 0 }conf ig, cn=conf ig 
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dn: olcDatabase={l}hdb,cn=conf ig 

Explanation of entries: 

• cn=config: global settings 

• cn=module{0},cn=config: a dynamically loaded module 

• cn=schema,cn=config: contains hard-coded system-level schema 

• cn={0}core,cn=schema,cn=config: the hard-coded core schema 

• cn={ 1 }cosine,cn= schema, cn=config: the cosine schema 

• cn={2}nis,cn=schema,cn=config: the nis schema 

• cn={ 3 }inetorgperson,cn=schema,cn=config: the inetorgperson schema 

• olcBackend={0}hdb,cn=config: the 'hdb' backend storage type 

• olcDatabase={ -1 }frontend,cn=config: frontend database, default settings for other databases 

• olcDatabase={0}config,cn=config\ slapd configuration database (cn=config) 

• olcDatabase={l}hdb,cn=config: your database instance (dc=examle,dc=com) 

• This is what the dc=example,dc=com DIT looks like: 

ldapsearch -x -LLL -H ldap:/// -b dc=example , dc=com dn 

dn: dc=example , dc=com 

dn: cn=admin, dc=example , dc=com 

Explanation of entries: 

• dc= example, dc= com: base of the DIT 

• cn=admin,dc=example,dc=com: administrator (rootDN) for this DIT (set up during package 
install) 

1.3. Modifying/Populating your Database 

Let's introduce some content to our database. We will add the following: 

• a node called People (to store users) 

• a node called Groups (to store groups) 

• a group called miners 

• a user called john 

Create the following LDIF file and call it add_content.ldif: 

dn: ou=People,dc=example,dc=com 
objectClass: organizationalUnit 
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ou: People 

dn: ou=Groups , dc=example , dc=com 
objectClass: organizationalUnit 
ou : Groups 

dn : cn=miners , ou=Groups , dc=example , dc=com 
objectClass: posixGroup 
cn: miners 
gidNumber: 5000 

dn: uid= john, ou=People , dc=example , dc=com 
objectClass: inetOrgPerson 
objectClass: posixAccount 
objectClass: shadowAccount 
uid: john 
sn: Doe 

givenName : John 
cn: John Doe 
displayName : John Doe 
uidNumber: 10000 
gidNumber: 5000 
userPassword : johnldap 
gecos : John Doe 
loginShell: /bin/bash 
homeDirectory : /home/john 

It's important that uid and gid values in your directory do not collide with local values. Use 
high number ranges, such as starting at 5000. By setting the uid and gid values in ldap high, 
you also allow for easier control of what can be done with a local user vs a ldap one. More 
on that later. 

Add the content: 

ldapadd -x -D cn=admin , dc=example , dc=com -W -f addcontent . ldif 

Enter LDAP Password: ******** 

adding new entry "ou=People , dc=example , dc=com" 

adding new entry "ou=Groups , dc=example , dc=com" 

adding new entry "cn=miners , ou=Groups , dc=example , dc=com" 

adding new entry "uid= john, ou=People , dc=example , dc=com" 

We can check that the information has been correctly added with the ldapsearch utility: 

ldapsearch -x -LLL -b dc=example,dc=com 'uid=john' cn gidNumber 

dn: uid= john, ou=People , dc=example , dc=com 
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cn: John Doe 
gidNumber: 5000 



Explanation of switches: 

• -x: "simple" binding; will not use the default SASL method 

• -LLL: disable printing extraneous information 

• uid=john: a "filter" to find the john user 

• cn gidNumber: requests certain attributes to be displayed (the default is to show all attributes) 

1.4. Modifying the slapd Configuration Database 

The slapd-config DIT can also be queried and modified. Here are a few examples. 

• Use ldapmodify to add an "Index" (Dblndex attribute) to your {l}hdb,cn=config database 
(dc=example,dc=com). Create a file, call it uid_index.ldif , with the following contents: 



dn: olcDatabase={ 1 }hdb, cn=conf ig 
add: olcDblndex 
olcDblndex: uid eq,pres,sub 

Then issue the command: 



sudo ldapmodify -Q -Y EXTERNAL -H ldapi:/// -f uid_index . ldif 

modifying entry "olcDatabase={ 1 }hdb, cn=conf ig" 

You can confirm the change in this way: 

sudo ldapsearch -Q -LLL -Y EXTERNAL -H ldapi:/// -b \ 
cn=config ' (olcDatabase={l}hdb) ' olcDblndex 

dn: olcDatabase={ 1 }hdb, cn=conf ig 
olcDblndex: objectClass eq 
olcDblndex: uid eq,pres,sub 

Let's add a schema. It will first need to be converted to LDIF format. You can find unconverted 
schemas in addition to converted ones in the /etc/idap/schema directory. 

• It is not trivial to remove a schema from the slapd-config database. Practice adding 
schemas on a test system. 

• Before adding any schema, you should check which schemas are already installed 
(shown is a default, out-of-the-box output): 



sudo ldapsearch -Q -LLL -Y EXTERNAL -H ldapi:/// -b \ 
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cn=schema , cn=conf ig dn 

dn: cn=schema, cn=conf ig 

dn : cn={ 0 }core , cn=schema, cn=conf ig 

dn : cn={ 1 } cosine , cn=schema, cn=conf ig 

dn: cn={2 }nis , cn=schema, cn=conf ig 

dn : cn={3 }inetorgperson , cn=schema, cn=conf ig 



In the following example we'll add the CORBA schema. 



1. Create the conversion configuration file schema_convert.conf containing the following lines: 



include /etc/ldap/schema/core . schema 

include /etc/ldap/schema/collective . schema 

include /etc/ldap/schema/corba . schema 

include /etc/ldap/schema/cosine . schema 

include /etc/ldap/schema/duaconf . schema 

include /etc/ldap/schema/dyngroup . schema 

include /etc/ldap/schema/inetorgperson . schema 

include /etc/ldap/schema/ java. schema 

include /etc/ldap/schema/misc . schema 

include /etc/ldap/schema/nis . schema 

include /etc/ldap/schema/openldap . schema 

include /etc/ldap/schema/ppolicy . schema 

include /etc/ldap/schema/ldapns . schema 

include /etc/ldap/schema/pmi . schema 

2. Create the output directory ldif_output. 

3 . Determine the index of the schema: 



slapcat -f schema_convert . conf -F ldif_output -n 0 | grep corba,cn=schema 

cn={ 1 }corba, cn=schema, cn=conf ig 



When slapd ingests objects with the same parent DN it will create an index for that 
object. An index is contained within braces: {X}. 

4. Use slapcat to perform the conversion: 



slapcat -f schema_convert . conf -F ldif_output -nO -H \ 
ldap: ///cn={l}corba,cn=schema,cn=conf ig -1 cn=corba . ldif 

The converted schema is now in cn=corba. ldif 
5. Edit cn=corba. ldif to arrive at the following attributes: 
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dn: cn=corba, cn=schema, cn=conf ig 
cn: corba 

Also remove the following lines from the bottom: 

structuralOb jectClass : olcSchemaConf ig 
entryUUID: 52 109a02-66ab-l 03 0-8be2-bbf 1662304 78 
creatorsName : cn=config 
createTimestamp: 20110829165435Z 

entryCSN: 20 1 10829 165435 . 935248Z#000000#000#000000 
modif iersName : cn=config 
modifyTimestamp: 20110829165435Z 

Your attribute values will vary. 
6. Finally, use ldapadd to add the new schema to the slapd-config DIT: 



sudo ldapadd -Q -Y EXTERNAL -H ldapi:/// -f cn\=corba. ldif 

adding new entry "cn=corba, cn=schema, cn=conf ig" 



7. Confirm currently loaded schemas: 



sudo ldapsearch -Q -LLL -Y EXTERNAL -H ldapi:/// -b cn=schema, cn=conf ig dn 

dn: cn=schema, cn=conf ig 

dn : cn={ 0 }core , cn=schema, cn=conf ig 

dn : cn={ 1 } cosine , cn=schema, cn=conf ig 

dn: cn={2 }nis , cn=schema, cn=conf ig 

dn : cn={3 }inetorgperson, cn=schema, cn=conf ig 

dn : cn={4 } corba, cn=schema, cn=conf ig 



For external applications and clients to authenticate using LDAP they will each need to 
be specifically configured to do so. Refer to the appropriate client-side documentation for 
details. 



1.5. Logging 

Activity logging for slapd is indispensible when implementing an OpenLDAP-based solution yet 
it must be manually enabled after software installation. Otherwise, only rudimentary messages 
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will appear in the logs. Logging, like any other slapd configuration, is enabled via the slapd-config 
database. 

OpenLDAP comes with multiple logging subsystems (levels) with each one containing the lower one 
(additive). A good level to try is stats. The slapd-config 7, man page has more to say on the different 
subsystems. 

Create the file logging, ldif with the following contents: 

dn: cn=config 
changetype: modify 
add: olcLogLevel 
olcLogLevel: stats 

Implement the change: 

sudo ldapmodify -Q -Y EXTERNAL -H ldapi:/// -f logging. ldif 

This will produce a significant amount of logging and you will want to throttle back to a less verbose 
level once your system is in production. While in this verbose mode your host's syslog engine 
(rsyslog) may have a hard time keeping up and may drop messages: 

rsyslogd-2177 : imuxsock lost 228 messages from pid 2547 due to rate-limiting 
You may consider a change to rsyslog's configuration. In /etc/rsysiog.conf , put: 

# Disable rate limiting 

# (default is 200 messages in 5 seconds; below we make the 5 become 0) 
$SystemLogRateLimitInterval 0 

And then restart the rsyslog daemon: 
sudo service rsyslog restart 

1.6. Replication 

The LDAP service becomes increasingly important as more networked systems begin to depend on it. 
In such an environment, it is standard practice to build redundancy (high availability) into LDAP to 
prevent havoc should the LDAP server become unresponsive. This is done through LDAP replication. 

Replication is achieved via the Syncrepl engine. This allows changes to be synchronized using a 
Consumer - Provider model. The specific kind of replication we will implement in this guide is a 
combination of the following modes: refreshAndPersist and delta-syncrepl. This has the Provider 
push changed entries to the Consumer as soon as they're made but, in addition, only actual changes 
will be sent, not entire entries. 



http://manpages.ubuntu.com/manpages/en/man5/slapd-config.5.html 
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1 .6.1 . Provider Configuration 
Begin by configuring the Provider. 

1 . Create an LDIF file with the following contents and name it provider sync . ldif : 

# Add indexes to the frontend db. 
dn: olcDatabase={ 1 }hdb, cn=conf ig 
changetype: modify 

add: olcDblndex 
olcDblndex: entryCSN eq 

add: olcDblndex 
olcDblndex: entryUUID eq 

#Load the syncprov and accesslog modules, 
dn: cn=module{0} ,cn=conf ig 
changetype: modify 
add: olcModuleLoad 
olcModuleLoad: syncprov 

add: olcModuleLoad 
olcModuleLoad: accesslog 

# Accesslog database definitions 
dn: olcDatabase={2 }hdb, cn=conf ig 
objectClass: olcDatabaseConf ig 
objectClass: olcHdbConfig 
olcDatabase: {2}hdb 

olcDbDirectory : /var/lib/ldap/ access log 
olcSuffix: cn=accesslog 
olcRootDN : cn=admin , dc=example , dc=com 
olcDblndex: default eq 

olcDblndex : entryCSN , ob j ectClass , reqEnd , reqResult , reqStart 

# Accesslog db syncprov. 

dn: olcOverlay=syncprov, olcDatabase={2}hdb, cn=conf ig 

changetype : add 

objectClass: olcOverlayConf ig 

objectClass: olcSyncProvConf ig 

olcOverlay: syncprov 

olcSpNoPresent: TRUE 

olcSpReloadHint : TRUE 

# syncrepl Provider for primary db 

dn: olcOverlay=syncprov, olcDatabase={ l}hdb, cn=conf ig 

changetype : add 

objectClass: olcOverlayConf ig 

objectClass: olcSyncProvConf ig 

olcOverlay: syncprov 

olcSpNoPresent: TRUE 
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# accesslog overlay definitions for primary db 

dn: olcOverlay=accesslog, olcDatabase={ l}hdb, cn=conf ig 

objectClass: olcOverlayConf ig 

objectClass: olcAccessLogConf ig 

olcOverlay: accesslog 

olcAccessLogDB : cn=accesslog 

olcAccessLogOps : writes 

olcAccessLogSuccess : TRUE 

# scan the accesslog DB every day, and purge entries older than 7 days 
olcAccessLogPurge: 07+00:00 01+00:00 

Change the rootDN in the LDIF file to match the one you have for your directory. 

2. The apparmor profile for slapd will need to be adjusted for the accesslog database location. Edit 
/etc/apparmor.d/local/usr.sbin.slapd by adding the following: 

/var/lib/ldap/accesslog/ r, 
/var/lib/ldap/accesslog/** rwk, 

Create a directory, set up a databse config file, and reload the apparmor profile: 
sudo -u openldap mkdir /var/lib/ldap/accesslog 

sudo -u openldap cp /var/lib/ldap/DB_CONFIG /var/lib/ldap/accesslog 
sudo service apparmor reload 

3. Add the new content and, due to the apparmor change, restart the daemon: 

sudo ldapadd -Q -Y EXTERNAL -H ldapi:/// -f provider_sync . ldif 
sudo service slapd restart 

The Provider is now configured. 

1.6.2. Consumer Configuration 

And now configure the Consumer. 

1. Install the software by going through Section 1.1, "Installation" [p. 92]. Make sure the 
slapd-config databse is identical to the Provider's. In particular, make sure schemas and the 
databse suffix are the same. 

2. Create an LDIF file with the following contents and name it consumersync . ldif: 

dn: cn=module{ 0 } , cn=conf ig 
changetype: modify 
add: olcModuleLoad 
olcModuleLoad: syncprov 

dn: olcDatabase={ 1 }hdb, cn=conf ig 
changetype: modify 
add: olcDblndex 
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olcDblndex: entryUUID eq 
add: olcSyncRepl 

olcSyncRepl: rid=0 provider=ldap : //IdapO 1 . example . com bindmethod=simple binddn="cn=admin, dc=exa 
credent ials=secret searchbase="dc=example , dc=com" logbase="cn=accesslog" 
logfilter=" ( & ( ob jectClass=auditWriteOb ject ) ( reqResult=0 ) ) " schemachecking=on 
type=ref reshAndPersist retry="60 +" syncdata=accesslog 

add: olcUpdateRef 

olcUpdateRef : ldap: // IdapO 1 . example . com 
Ensure the following attributes have the correct values: 

• provider (Provider server's hostname — IdapO 1 .example.com in this example — or IP address) 

• binddn (the admin DN you're using) 

• credentials (the admin DN password you're using) 

• searchbase (the database suffix you're using) 

• olcUpdateRef (Provider server's hostname or IP address) 

• rid (Replica ID, an unique 3-digit that identifies the replica. Each consumer should have at 
least one rid) 

3. Add the new content: 

sudo ldapadd -Q -Y EXTERNAL -H ldapi:/// -f consume rsy nc . ldif 

You're done. The two databases (suffix: dc=example,dc=com) should now be synchronizing. 
1.6.3. Testing 

Once replication starts, you can monitor it by running 

ldapsearch -zl -LLLQY EXTERNAL -H ldapi:/// -s base -b dc=example,dc=com contextCSN 

dn: dc=example , dc=com 

contextCSN: 20120201193408 . 178454Z#000000#000#000000 
on both the provider and the consumer. Once the output 

(20120201193408. i78454z#oooooo#ooo#oooooo in the above example) for both machines match, you 
have replication. Every time a change is done in the provider, this value will change and so should the 
one in the consumer(s). 

If your connection is slow and/or your ldap database large, it might take a while for the consumer's 
contextCSN match the provider's. But, you will know it is progressing since the consumer's 
contextCSN will be steadly increasing. 

If the consumer's contextCSN is missing or does not match the provider, you should stop and figure 
out the issue before continuing. Try checking the slapd (syslog) and the auth log files in the provider 
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to see if the consumer's authentication requests were successful or its requests to retrieve data (they 
look like a lot of ldapsearch statements) return no errors. 

To test if it worked simply query, on the Consumer, the DNs in the database: 

sudo ldapsearch -Q -LLL -Y EXTERNAL -H ldapi:/// -b dc=example,dc=com dn 

You should see the user 'john' and the group 'miners' as well as the nodes 'People' and 'Groups'. 

1.7. Access Control 

The management of what type of access (read, write, etc) users should be granted to resources is 
known as access control. The configuration directives involved are called access control lists or ACL. 

When we installed the slapd package various ACL were set up automatically. We will look at a few 
important consequences of those defaults and, in so doing, we'll get an idea of how ACLs work and 
how they're configured. 

To get the effective ACL for an LDAP query we need to look at the ACL entries of the database 
being queried as well as those of the special frontend database instance. The ACLs belonging to the 
latter act as defaults in case those of the former do not match. The frontend database is the second 
to be consulted and the ACL to be applied is the first to match ("first match wins") among these 
2 ACL sources. The following commands will give, respectively, the ACLs of the hdb database 
("dc=example,dc=com") and those of the frontend database: 

sudo ldapsearch -Q -LLL -Y EXTERNAL -H ldapi:/// -b \ 
cn=config ' (olcDatabase={l}hdb) ' olcAccess 

dn: olcDatabase={ 1 }hdb, cn=conf ig 

olcAccess: {0}to attrs=userPassword, shadowLastChange by self write by anonymous 

auth by dn="cn=admin , dc=example , dc=com" write by * none 
olcAccess: {l}to dn.base="" by * read 

olcAccess: {2}to * by self write by dn="cn=admin , dc=example , dc=com" write by * 
read 



The rootDN always has full rights to it's database. Including it in an ACL does provide an 
explicit configuration but it also causes slapd to incur a performance penalty. 



sudo ldapsearch -Q -LLL -Y EXTERNAL -H ldapi:/// -b \ 
cn=config ' (olcDatabase={-l}f rontend) ' olcAccess 

dn : olcDatabase={-l }f rontend, cn=conf ig 

olcAccess: {0}to * by dn . exact=gidNumber=0+uidNumber=0 , cn=peercred, 

cn=external , cn=auth manage by * break 
olcAccess: {l}to dn.exact="" by * read 
olcAccess: {2}to dn.base="cn=Subschema" by * read 
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The very first ACL is crucial: 

olcAccess: {0}to attrs=userPassword, shadowLastChange by self write by anonymous 
auth by dn="cn=admin, dc=example , dc=com" write by * none 

This can be represented differently for easier digestion: 

to attrs=userPassword 
by self write 
by anonymous auth 

by dn="cn=admin, dc=example , dc=com" write 
by * none 

to attrs=shadowLastChange 
by self write 
by anonymous auth 

by dn="cn=admin, dc=example , dc=com" write 
by * none 

This compound ACL (there are 2) enforces the following: 

• Anonymous 'auth' access is provided to the userPassword attribute for the initial connection to 
occur. Perhaps counter-intuitively, 'by anonymous auth' is needed even when anonymous access to 
the DIT is unwanted. Once the remote end is connected, howerver, authentication can occur (see 
next point). 

• Authentication can happen because all users have 'read' (due to 'by self write') access to the 
userPassword attribute. 

• The userPassword attribute is otherwise unaccessible by all other users, with the exception of the 
rootDN, who has complete access to it. 

• In order for users to change their own password, using passwd or other utilities, the 
shadowLastChange attribute needs to be accessible once a user has authenticated. 

This DIT can be searched anonymously because of 'by * read' in this ACL: 

to * 
by self write 

by dn="cn=admin, dc=example , dc=com" write 
by * read 

If this is unwanted then you need to change the ACLs. To force authentication during a bind request 
you can alternatively (or in combination with the modified ACL) use the 'olcRequire: authc' directive. 

As previously mentioned, there is no administrative account created for the slapd-config database. 
There is, however, a SASL identity that is granted full access to it. It represents the localhost's 
superuser (root/sudo). Here it is: 



104 



Network Authentication 



dn . exact=gidNumber=0+uidNumber=0 , cn=peercred, cn=external , cn=auth 
The following command will display the ACLs of the slapd-config database: 

sudo ldapsearch -Q -LLL -Y EXTERNAL -H ldapi:/// -b \ 
cn=config ' (olcDatabase={0}conf ig) ' olcAccess 

dn: olcDatabase={0}conf ig, cn=conf ig 

olcAccess: {0}to * by dn . exact=gidNumber=0+uidNumber=0 , cn=peercred, 
cn=external , cn=auth manage by * break 

Since this is a SASL identity we need to use a SASL mechanism when invoking the LDAP utility in 
question and we have seen it plenty of times in this guide. It is the EXTERNAL mechanism. See the 
previous command for an example. Note that: 

1 . You must use sudo to become the root identity in order for the ACL to match. 

2. The EXTERNAL mechanism works via IPC (UNIX domain sockets). This means you must use 
the ldapi URI format. 

A succinct way to get all the ACLs is like this: 

sudo ldapsearch -Q -LLL -Y EXTERNAL -H ldapi:/// -b \ 
cn=config ' (olcAccess=* ) ' olcAccess olcSuffix 

There is much to say on the topic of access control. See the man page for slapd. access 4 . 

1.8. TLS 

When authenticating to an OpenLDAP server it is best to do so using an encrypted session. This can 
be accomplished using Transport Layer Security (TLS) . 

Here, we will be our own Certificate Authority and then create and sign our LDAP server certificate 
as that CA. Since slapd is compiled using the gnutls library, we will use the certtool utility to 
complete these tasks. 

1 . Install the gnutls-bin and ssl-cert packages: 

sudo apt-get install gnutls-bin ssl-cert 

2. Create a private key for the Certificate Authority: 

sudo sh -c "certtool — generate-privkey > /etc/ssl/private/cakey .pern" 

4 http://manpages.ubuntu.eom/manpages/en/man5/slapd.access.5.html 
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3. Create the template/file /etc/ssl/ca. inf o to define the CA: 

cn = Example Company 
ca 

cert_signing_key 

4. Create the self-signed CA certificate: 

sudo certtool --generate-self-signed \ 
--load-privkey /etc/ssl/private/cakey .pern \ 
--template /etc/ssl/ca . inf o \ 
--out file /etc/ssl /certs /cacert .pern 

5. Make a private key for the server: 

sudo certtool --generate-privkey \ 
--bits 1024 \ 

--out file /etc/ssl /private /ldap01_slapd_key.pem 

*— I Replace IdapOl in the filename with your server's hostname. Naming the certificate and 
key for the host and service that will be using them will help keep things clear. 

6. Create the /etc/ssl/ldapOl .info info file containing: 

organization = Example Company 

cn = ldap01.example.com 

tls_www_server 

encrypt ion_key 

signing_key 

expiration_days = 3650 

The above certificate is good for 10 years. Adjust accordingly. 

7. Create the server's certificate: 

sudo certtool --generate-certif icate \ 

--load-privkey /etc/ssl/private/ldap01_slapd_key .pern \ 
--load-ca-certif icate /etc/ssl/certs/cacert .pern \ 
--load-ca-privkey /etc/ssl/private/cakey .pern \ 
--template /etc/ssl/ldapOl . inf o \ 
--outf ile /etc/ssl/certs/ldap01_slapd_cert .pern 

Create the file certinfo.ldif with the following contents (adjust accordingly, our example assumes 
we created certs using https://www.cacert.org): 

dn: cn=config 

add: olcTLSCACertif icateFile 

olcTLSCACertif icateFile : /etc/ssl/certs/cacert . pern 
add: olcTLSCertif icateFile 
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olcTLSCertif icateFile : /etc/ssl/certs/ldapO l_slapd_cert . pem 
add: olcTLSCertif icateKeyFile 

olcTLSCertif icateKeyFile : /etc/ssl/private/ldapO l_slapd_key . pem 

Use the ldapmodify command to tell slapd about our TLS work via the slapd-config database: 



sudo ldapmodify -Y EXTERNAL -H ldapi:/// -f /etc/ssl/certinfo. ldif 

Contratry to popular belief, you do not need Idaps:// in /etc/def ault/slapd in order to use 
encryption. You should have just: 



SLAPD_SERVICES="ldap: /// ldapi: ///" 

LDAP over TLS/SSL (ldaps://) is deprecated in favour of StartTLS. The latter refers to 
an existing LDAP session (listening on TCP port 389) becoming protected by TLS/SSL 
whereas LDAPS, like HTTPS, is a distinct encrypted-from-the-start protocol that operates 
over TCP port 636. 

Tighten up ownership and permissions: 



sudo adduser openldap ssl-cert 

sudo chgrp ssl-cert /etc/ssl/private/ldap01_slapd_key .pem 
sudo chmod g+r /etc/ssl/private/ldap01_slapd_key .pem 
sudo chmod o-r /etc/ssl/private/ldap01_slapd_key .pem 



Restart OpenLDAP: 



sudo service slapd restart 

Check your host's logs (/var/log/syslog) to see if the server has started properly. 

1 .9 . Replication and TLS 

If you have set up replication between servers, it is common practice to encrypt (StartTLS) the 
replication traffic to prevent evesdropping. This is distinct from using encryption with authentication 
as we did above. In this section we will build on that TLS-authentication work. 

The assumption here is that you have set up replication between Provider and Consumer according to 
Section 1.6, "Replication" [p. 99] and have configured TLS for authentication on the Provider by 
following Section 1.8, "TLS" [p. 105]. 

As previously stated, the objective (for us) with replication is high availablity for the LDAP service. 
Since we have TLS for authentication on the Provider we will require the same on the Consumer. 
In addition to this, however, we want to encrypt replication traffic. What remains to be done is to 
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create a key and certificate for the Consumer and then configure accordingly. We will generate the 
key/certificate on the Provider, to avoid having to create another CA certificate, and then transfer the 
necessary material over to the Consumer. 

1. On the Provider, 

Create a holding directory (which will be used for the eventual transfer) and then the Consumer's 
private key: 

mkdir ldap02-ssl 
cd ldap02-ssl 

sudo certtool --generate-privkey \ 
—bits 1024 \ 

— outfile ldap02_slapd_key .pem 

Create an info file, idap02 .info, for the Consumer server, adjusting it's values accordingly: 

organization = Example Company 

cn = ldap02.example.com 

tls_www_server 

encrypt ion_key 

signing_key 

expiration_days = 3650 
Create the Consumer's certificate: 

sudo certtool — generate-certif icate \ 

--load-privkey ldap02_slapd_key .pern \ 

— load-ca-certif icate /etc/ssl/certs/cacert .pem \ 

— load-ca-privkey /etc/ssl/private/cakey .pem \ 

--template ldap02.info \ 

— outfile ldap02_slapd_cert.pem 

Get a copy of the CA certificate: 
cp /etc/ssl/certs/cacert. pem . 

We're done. Now transfer the idap02-ssi directory to the Consumer. Here we use scp (adjust 
accordingly): 

cd . . 

scp -r ldap02-ssl user@consumer : 

2. On the Consumer, 

Configure TLS authentication: 
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sudo apt-get install ssl-cert 
sudo adduser openldap ssl-cert 

sudo cp ldap02_slapd_cert.pem cacert.pem /etc/ssl/certs 
sudo cp ldap02_slapd_key .pem /etc/ssl/private 
sudo chgrp ssl-cert /etc/ssl/private/ldap02_slapd_key .pern 
sudo chmod g+r /etc/ssl/private/ldap02_slapd_key .pem 
sudo chmod o-r /etc/ssl/private/ldap02_slapd_key .pem 

Create the file /etc/ssl/certinfo.ldif with the following contents (adjust accordingly): 
dn: cn=config 

add: olcTLSCACertif icateFile 

olcTLSCACertif icateFile : /etc /ssl /certs /cacert . pem 
add: olcTLSCertif icateFile 

olcTLSCertif icateFile : /etc /ssl /certs / IdapO 2_slapd_cert . pem 
add: olcTLSCertif icateKeyFile 

olcTLSCertif icateKeyFile : /etc/ssl/private/ldap02_slapd_key . pem 
Configure the slapd-config database: 

sudo ldapmodify -Y EXTERNAL -H ldapi:/// -f certinfo. ldif 

Configure /etc/def auit/siapd as on the Provider (SLAPD_SER VICES) . 
3. On the Consumer, 

Configure TLS for Consumer-side replication. Modify the existing olcSyncrepl attribute by 
tacking on some TLS options. In so doing, we will see, for the first time, how to change an 
attribute's value(s). 

Create the file consumer_sync_tis . ldif with the following contents: 

dn: olcDatabase={l}hdb,cn=conf ig 
replace: olcSyncRepl 

olcSyncRepl: rid=0 provider=ldap : //IdapO 1 . example . com bindmethod=simple 
binddn= " cn=admin , dc=example , dc=com" credentials=secret searchbase= " dc=example , dc= 
logbase="cn=accesslog" logfilter=" ( & ( ob jectClass=auditWriteOb ject ) ( reqResult=0 ) ) " 
schemachecking=on type=ref reshAndPersist retry="60 +" syncdata=accesslog 
starttls=critical tls_reqcert=demand 

The extra options specify, respectively, that the consumer must use StartTLS and that the CA 
certificate is required to verify the Provider's identity. Also note the LDIF syntax for changing 
the values of an attribute ('replace'). 

Implement these changes: 

sudo ldapmodify -Y EXTERNAL -H ldapi:/// -f consumer_sync_tls . ldif 
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And restart slapd: 

sudo service slapd restart 

4. On the Provider, 

Check to see that a TLS session has been established. In /var/iog/syslog, providing you have 
'conns'-level logging set up, you should see messages similar to: 

slapd[3620]: conn=1047 fd=20 ACCEPT from IP=10 . 153 . 107 . 229 : 57922 ( IP=0 . 0 . 0 . 0 : 389 ) 

slapd[3620]: conn=1047 op=0 EXT oid=l . 3 . 6 . 1 . 4 . 1 . 1466 . 20037 

slapd[3620]: conn=1047 op=0 STARTTLS 

slapd[3620]: conn=1047 op=0 RESULT oid= err=0 text= 

slapd[3620]: conn=1047 fd=20 TLS established tls_ssf=128 ssf=128 

slapd[3620]: conn=1047 op=l BIND dn="cn=admin, dc=example , dc=com" method=128 

slapd[3620]: conn=1047 op=l BIND dn="cn=admin, dc=example , dc=com" mech=SIMPLE ssf=0 

slapd[3620]: conn=1047 op=l RESULT tag=97 err=0 text 

1.10. LDAP Authentication 

Once you have a working LDAP server, you will need to install libraries on the client that will know 
how and when to contact it. On Ubuntu, this has been traditionally accomplished by installing the 
libnss-ldap package. This package will bring in other tools that will assist you in the configuration 
step. Install this package now: 

sudo apt-get install libnss-ldap 

You will be prompted for details of your LDAP server. If you make a mistake you can try again 
using: 

sudo dpkg-reconf igure ldap-auth-conf ig 

The results of the dialog can be seen in /etc/idap.conf . If your server requires options not covered 
in the menu edit this file accordingly. 

Now configure the LDAP profile for NSS: 

sudo auth-client-conf ig -t nss -p lac_ldap 

Configure the system to use LDAP for authentication: 

sudo pam-auth-update 

From the menu, choose LDAP and any other authentication mechanisms you need. 
You should now be able to log in using LDAP-based credentials. 
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LDAP clients will need to refer to multiple servers if replication is in use. In /etc/ldap.conf you 
would have something like: 



uri ldap : //ldapO 1 . example . com ldap : //ldap02 . example . com 

The request will time out and the Consumer (ldap02) will attempt to be reached if the Provider 
(IdapOl) becomes unresponsive. 

If you are going to use LDAP to store Samba users you will need to configure the Samba server to 
authenticate using LDAP. See Section 2, "Samba and LDAP" [p. 117] for details. 

I%— I An alternative to the libnss-ldap package is the libnss-ldapd package. This, however, will 
bring in the nscd package which is problably not wanted. Simply remove it afterwards. 

1.11. User and Group Management 

The ldap-utils package comes with enough utilities to manage the directory but the long string of 
options needed can make them a burden to use. The ldapscripts package contains wrapper scripts to 
these utilities that some people find easier to use. 

Install the package: 

sudo apt-get install ldapscripts 

Then edit the file /etc/ldapscripts/ldapscripts.conf to arrive at something similar to the 
following: 



SERVER=localhost 

BINDDN= ' cn=admin , dc=example , dc=com ' 

BINDPWDFILE=" /etc /ldapscripts/ ldapscripts . passwd" 

SUFFIX= ' dc=example , dc=com ' 

GSUFFIX= ' ou=Groups ' 

USUFFIX= ' ou=People ' 

MSUFFIX= ' ou=Computers ' 

GIDSTART=10000 

UIDSTART=10000 

MIDSTART=10000 

Now, create the ldapscripts .passwd file to allow rootDN access to the directory: 



sudo sh -c "echo -n 'secret' > /etc/ldapscripts/ldapscripts .passwd" 
sudo chmod 400 /etc/ldapscripts/ldapscripts .passwd 

a — I Replace "secret" with the actual password for your database's rootDN user. 



The scripts are now ready to help manage your directory. Here are some examples of how to use 
them: 
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• Create a new user: 

sudo ldapadduser george example 

This will create a user with uid george and set the user's primary group (gid) to example 

• Change a user's password: 

sudo ldapsetpasswd george 

Changing password for user uid=george , ou=People , dc=example , dc=com 

New Password: 

New Password (verify) : 

• Delete a user: 

sudo ldapdeleteuser george 

• Add a group: 

sudo ldapaddgroup qa 

• Delete a group: 

sudo ldapdeletegroup qa 

• Add a user to a group: 

sudo ldapaddusertogroup george qa 

You should now see a member Uid attribute for the qa group with a value of george. 

• Remove a user from a group: 

sudo ldapdeleteuserf romgroup george qa 

The memberUid attribute should now be removed from the qa group. 

• The ldapmodifyuser script allows you to add, remove, or replace a user's attributes. The script uses 
the same syntax as the ldapmodify utility. For example: 

sudo ldapmodifyuser george 

# About to modify the following entry : 

dn : uid=george , ou=People , dc=example , dc=com 

objectClass: account 

objectClass: posixAccount 

cn: george 

uid: george 

uidNumber: 1001 

gidNumber: 1001 

homeDirectory : /home/george 
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loginShell: /bin/bash 
gecos: george 
description: User account 

userPassword: : elNTSEF9eXFsTFcyWlhwWkFleGUybVdFWHZKRz JVMjFTSG9vcHk= 

# Enter your modifications here, end with CTRL-D. 
dn : uid=george , ou=People , dc=example , dc=com 
replace: gecos 
gecos: George Carlin 

The user's gecos should now be "George Carlin". 

• A nice feature of ldapscripts is the template system. Templates allow you to customize the 

attributes of user, group, and machine objects. For example, to enable the user template edit /etc/ 
ldapscripts/ldapscripts . conf changing: 

UTEMPLATE=" /etc/ldapscripts/ldapadduser . template" 

There are sample templates in the /etc/ldapscripts directory. Copy or rename the 
ldapadduser . template . sample file to /etc/ldapscripts/ldapadduser . template: 

sudo cp /usr/share/doc/ldapscripts/examples/ldapadduser. template. sample \ 
/etc/ldapscripts/ldapadduser .template 

Edit the new template to add the desired attributes. The following will create new users with an 
objectClass of inetOrgPerson: 

dn: uid=<user> ,<usuf f ix> ,<suf f ix> 

objectClass: inetOrgPerson 

objectClass: posixAccount 

cn: <user> 

sn: <ask> 

uid: <user> 

uidNumber : <uid> 

gidNumber : <gid> 

homeDirectory : <home> 

loginShell: <shell> 

gecos : <user> 

description: User account 

title: Employee 

Notice the <ask> option used for the sn attribute. This will make ldapadduser prompt you for it's 
value. 

There are utilities in the package that were not covered here. Here is a complete list: 
Ida pren amemachine 5 



http://manpages.ubuntu.eom/manpages/en/manl/ldaprenamemachine.l.html 
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ldapadduser 6 

ldapdeleteuserfromgroup 

ldapfinger 

ldapid 9 

ldapgid 10 

Idapmodifyuser 11 

1 9 

ldaprenameuser 
Isldap 13 

ldapaddusertogroup 14 

Idapsetpasswd 15 

ldapinit 16 

1 H 

ldapaddgroup 

1 Q 

ldapdeletegroup 

1 Q 

ldapmodifygroup 

20 

ldapdeletemachme 

21 

2 dapr en ame gr o up 

22 

ldapaddmachme 
ldapmodifymachme 
Idapsetprimarygroup 24 
Idapdeleteuser* 5 

1.12. Backup and Restore 

Now we have ldap running just the way we want, it is time to ensure we can save all of our work and 
restore it as needed. 

What we need is a way to backup the ldap database(s) , specifically the backend (cn=config) and 
frontend (dc=example,dc=com). if we are going to backup those databases into, say, /export/backup, 
we could use slapcat as shown in the following script, called /usr/local/bin/idapbackup: 



#! /bin/bash 



" http://manpages.ubuntu.eom/manpages/en/manl/ldapadduser.l.html 
http://manpages.ubuntu.eom/manpages/en/manl/ldapdeleteuserfromgroup.l.html 

Q 

http://manpages.ubuntu.eom/manpages/en/manl/ldapfinger.l .html 

o 

http://manpages.ubuntu.eom/manpages/en/manl/ldapid.l .html 

http://manpages.ubuntu.eom/manpages/en/manl/ldapgid.l .html 

' ' http://manpages.ubuntu.eom/manpages/en/manl/ldapmodifyuser.l .html 
1 2 

http://manpages.ubuntu.eom/manpages/en/manl/ldaprenameuser.l.html 

i -i 

http://manpages.ubuntu.eom/manpages/en/manl/lsldap.l.html 
http://manpages.ubuntu.eom/manpages/en/manl/ldapaddusertogroup.l.html 
' http://manpages.ubuntu.eom/manpages/en/manl/ldapsetpasswd.l.html 
' http://manpages.ubuntu.eom/manpages/en/manl/ldapinit.l .html 
http://manpages.ubuntu.eom/manpages/en/manl/ldapaddgroup.l.html 

1 Q 

http://manpages.ubuntu.eom/manpages/en/manl/ldapdeletegroup.l.html 

19 http://manpages.ubuntu.eom/manpages/en/manl/ldapmodifygroup.l.html 

20 

http://manpages.ubuntu.eom/manpages/en/manl/ldapdeletemachine.l.html 

21 

http://manpages.ubuntu.eom/manpages/en/manl/ldaprenamegroup.l.html 

22 

http://manpages.ubuntu.eom/manpages/en/manl/ldapaddmachine.l.html 

23 

http://manpages.ubuntu.eom/manpages/en/manl/ldapmodifymachine.l.html 

24 http://manpages.ubuntu.eom/manpages/en/manl/ldapsetprimarygroup.l.html 
25 

http://manpages.ubuntu.eom/manpages/en/manl/ldapdeleteuser.l.html 
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BACKUP_PATH= / export /backup 
SLAPCAT=/usr/sbin/slapcat 



nice ${SLAPCAT} -n 0 > $ {BACKUP_PATH} /conf ig . ldif 
nice ${SLAPCAT} -n 1 > $ {BACKUP_PATH} /example . com . ldif 
nice ${SLAPCAT} -n 2 > $ {BACKUP_PATH} /access . ldif 
chmod 640 $ {BACKUP_PATH} / * . ldif 



These files are uncompressed text files containing everything in your ldap databases 
including the tree layout, usernames, and every password. So, you might want to consider 
making /export/backup an encrypted partition and even having the script encrypt those 
files as it creates them. Ideally you should do both, but that depends on your security 
requirements. 

Then, it is just a matter of having a cron script to run this program as often as we feel comfortable 
with. For many, once a day suffices. For others, more often is required. Here is an example of a cron 
script called /etc/cron.d/idapbackup that is run every night at 22:45h: 



MAILTO=backup-emails@domain . com 

45 22 * * * root /usr/local/bin/ldapbackup 

Now the files are created, they should be copied to a backup server. 



Assuming we did a fresh reinstall of ldap, the restore process could be something like this: 



sudo service slapd stop 

sudo mkdir /var/lib/ldap/accesslog 

sudo slapadd -F /etc/ldap/slapd.d -n 0 -1 /export/backup/conf ig . ldif 
sudo slapadd -F /etc/ldap/slapd.d -n 1 -1 /export/backup/domain. com. ldif 
sudo slapadd -F /etc/ldap/slapd.d -n 2 -1 /export/backup/access . ldif 
sudo chown -R openldap : openldap /etc/ldap/slapd.d/ 
sudo chown -R openldap: openldap /var/lib/ldap/ 
sudo service slapd start 

1.13. Resources 

• The primary resource is the upstream documentation: www.openldap.org 26 

• There are many man pages that come with the slapd package. Here are some important ones, 
especially considering the material presented in this guide: 



slapd 1 ' 

slapd-config 1 ' 
slapd. access 



http://www.openldap.org/ 

http://manpages.ubuntu.eom/manpages/en/man8/slapd.8.html 
http://manpages.ubuntu.eom/manpages/en/man5/slapd-config.5 .html 
http://manpages.ubuntu.eom/manpages/en/man5/slapd.access.5 .html 
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slapo-syncprov 30 

• Other man pages: 

auth-client-config^ 1 
pam-auth-update 

• Zytrax's LDAPfor Rocket Scientists 33 ; a less pedantic but comprehensive treatment of LDAP 

• A Ubuntu community OpenLDAP wiki 34 page has a collection of notes 

• O'Reilly's LDAP System Administration 35 (textbook; 2003) 

• Packt's Mastering OpenLDAP 36 (textbook; 2007) 



http://manpages.ubuntu.com/manpages/en/man5/slapo-syncprov.5.html 

http://manpages.ubuntu.eom/manpages/en/man8/auth-client-config.8.html 

http://manpages.ubuntu.eom/manpages/en/man8/pam-auth-update.8.html 

http://www.zytrax.com/books/ldap/ 

https://help.ubuntu.com/community/OpenLDAPServer 

http://www.oreilly.com/catalog/ldapsa/ 

http://www.packtpub.com/OpenLDAP-Developers-Server-Open-Source-Linux/book 
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2. Samba and LDAP 

This section covers the integration of Samba with LDAP. The Samba server's role will be that of 
a "standalone" server and the LDAP directory will provide the authentication layer in addition to 
containing the user, group, and machine account information that Samba requires in order to function 
(in any of it's 3 possible roles) . The pre -requisite is an OpenLDAP server configured with a directory 
that can accept authentication requests. See Section 1, "OpenLDAP Server" [p. 91 ] for details on 
fulfilling this requirement. Once this section is completed, you will need to decide what specifically 
you want Samba to do for you and then configure it accordingly. 

2.1. Software Installation 



There are three packages needed when integrating Samba with LDAP: samba, samba-doc, and 
smbldap-tools packages. 

Strictly speaking, the smbldap-tools package isn't needed, but unless you have some other way to 
manage the various Samba entities (users, groups, computers) in an LDAP context then you should 
install it. 



Install these packages now: 



sudo apt-get install samba samba-doc smbldap-tools 

2.2. LDAP Configuration 

We will now configure the LDAP server so that it can accomodate Samba data. We will perform three 
tasks in this section: 

1 . Import a schema 

2. Index some entries 

3. Add objects 

2.2.1 . Samba schema 

In order for OpenLDAP to be used as a backend for Samba, logically, the DIT will need to use 
attributes that can properly describe Samba data. Such attributes can be obtained by introducing a 
Samba LDAP schema. Let's do this now. 

*— I For more information on schemas and their installation see Section 1 .4, "Modifying the 
slapd Configuration Database" [p. 96]. 

1. The schema is found in the now-installed samba-doc package. It needs to be unzipped and copied 
to the /etc/idap/schema directory: 
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sudo cp /usr/share/doc/samba-doc/examples/LDAP/samba. schema. gz /etc/ldap/schema 
sudo gzlp -d /etc/ldap/schema/samba . schema .gz 

2. Have the configuration file schema_convert . conf that contains the following lines: 



include /etc/ldap/schema/core . schema 

include /etc/ldap/schema/collective . schema 

include /etc/ldap/schema/corba . schema 

include /etc/ldap/schema/cosine . schema 

include /etc/ldap/schema/duaconf . schema 

include /etc/ldap/schema/dyngroup . schema 

include /etc/ldap/schema/inetorgperson . schema 

include /etc/ldap/schema/ java. schema 

include /etc/ldap/schema/misc . schema 

include /etc/ldap/schema/nis . schema 

include /etc/ldap/schema/openldap . schema 

include /etc/ldap/schema/ppolicy . schema 

include /etc/ldap/schema/ldapns . schema 

include /etc/ldap/schema/pmi . schema 

include /etc/ldap/schema/samba. schema 

3. Have the directory ldif output hold output. 

4. Determine the index of the schema: 



slapcat -f schema_convert.conf -F ldif_output -n 0 | grep samba, cn=schema 

dn: cn={ 14 } samba, cn=schema, cn=config 

5. Convert the schema to LDIF format: 



slapcat -f schema_convert.conf -F ldif_output -nO -H \ 
ldap: ///cn={14}samba,cn=schema,cn=conf ig -1 cn=samba. ldif 

6. Edit the generated cn=samba . ldif file by removing index information to arrive at: 

dn: cn=samba, cn=schema, cn=conf ig 
cn: samba 

Remove the bottom lines: 



structuralOb jectClass : olcSchemaConf ig 
entryUUID: b53b75ca-083f-102d-9f f f-2f 64f dl23c95 
creatorsName : cn=config 
createTimestamp: 20080827045234Z 

entryCSN: 20080827045234 . 34 1425Z#000000#000#000000 
modif iersName : cn=config 
modifyTimestamp: 20080827045234Z 

Your attribute values will vary. 
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7. Add the new schema: 



sudo ldapadd -Q -Y EXTERNAL -H ldapi:/// -f cn\=samba . ldif 

To query and view this new schema: 



sudo ldapsearch -Q -LLL -Y EXTERNAL -H ldapi:/// -b cn=schema , cn=conf ig 'cn=*samba*' 

2.2.2. Samba indices 

Now that slapd knows about the Samba attributes, we can set up some indices based on them. 
Indexing entries is a way to improve performance when a client performs a filtered search on the DIT. 

Create the file samba_indices . ldif with the following contents: 



dn: olcDatabase={ 1 }hdb, cn=conf ig 

changetype: modify 
add: olcDblndex 

olcDblndex: uidNumber eq 

olcDblndex: gidNumber eq 

olcDblndex: loginShell eq 

olcDblndex: uid eq,pres,sub 

olcDblndex: memberUid eq,pres,sub 

olcDblndex: uniqueMember eq,pres 

olcDblndex: sambaSID eq 

olcDblndex: sambaPrimaryGroupSID eq 

olcDblndex: sambaGroupType eq 

olcDblndex: sambaSIDList eq 

olcDblndex: sambaDomainName eq 

olcDblndex: default sub 

Using the ldapmodify utility load the new indices: 



sudo ldapmodify -Q -Y EXTERNAL -H ldapi:/// -f sambaindices . ldif 

If all went well you should see the new indices using ldapsearch: 



sudo ldapsearch -Q -LLL -Y EXTERNAL -H \ 

ldapi:/// -b cn=config olcDatabase={ 1 }hdb olcDblndex 

2.2.3. Adding Samba LDAP objects 

Next, configure the smbldap-tools package to match your environment. The package is supposed 
to come with a configuration helper script (smbldap-config.pl, formerly configure.pl) that will ask 
questions about the needed options but there is a bug 37 whereby it is not installed (but found in the 
source code; 'apt-get source smbldap-tools'). 



https://bugs.launchpad.net/serverguide/+bug/997172 
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To manually configure the package, you need to create and edit the files /etc/smbidap-toois/ 
smbldap.conf and /etc/smbldap-tools/smbldap_bind . conf . 

The smbldap-populate script will then add the LDAP objects required for Samba. It is a good idea to 
first make a backup of your DIT using slapcat: 

sudo slapcat -1 backup. ldif 

Once you have a backup proceed to populate your directory: 
sudo smbldap-populate 

You can create a LDIF file containing the new Samba objects by executing sudo smbldap-populate 
-e samba. ldif. This allows you to look over the changes making sure everything is correct. If it is, 
rerun the script without the '-e' switch. Alternatively, you can take the LDIF file and import it's data 
per usual. 

Your LDAP directory now has the necessary information to authenticate Samba users. 

2.3. Samba Configuration 

There are multiple ways to configure Samba. For details on some common configurations see 
Chapter 18, Samba [p. 281 ]. To configure Samba to use LDAP, edit it's configuration file /etc/ 
samba/ smb. conf commenting out the default passdb backend parameter and adding some ldap-related 
ones: 

# passdb backend = tdbsam 

# LDAP Settings 

passdb backend = ldapsam: ldap: //hostname 

ldap suffix = dc=example , dc=com 

ldap user suffix = ou=People 

ldap group suffix = ou=Groups 

ldap machine suffix = ou=Computers 

ldap idmap suffix = ou=Idmap 

ldap admin dn = cn=admin, dc=example , dc=com 

ldap ssl = start tls 

ldap passwd sync = yes 

add machine script = sudo /usr/sbin/smbldap-useradd -t 0 -w "%u" 
Change the values to match your environment. 
Restart samba to enable the new settings: 

sudo restart smbd 
sudo restart nmbd 
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Now inform Samba about the rootDN user's password (the one set during the installation of the slapd 
package): 

sudo smbpasswd -w password 

If you have existing LDAP users that you want to include in your new LDAP-backed Samba they 
will, of course, also need to be given some of the extra attributes. The smbpasswd utility can do this 
as well (your host will need to be able to see (enumerate) those users via NSS; install and configure 
either libnss-ldapd or libnss-ldap): 

sudo smbpasswd -a username 

You will prompted to enter a password. It will be considered as the new password for that user. 
Making it the same as before is reasonable. 

To manage user, group, and machine accounts use the utilities provided by the smbldap-tools 
package. Here are some examples: 

• To add a new user: 

sudo smbldap-useradd -a -P username 

The -a option adds the Samba attributes, and the -P option calls the smbldap-passwd utility after the 
user is created allowing you to enter a password for the user. 

• To remove a user: 

sudo smbldap-userdel username 

In the above command, use the -r option to remove the user's home directory. 

• To add a group: 

sudo smbldap-groupadd -a groupname 

As for smbldap-useradd, the -a adds the Samba attributes. 

• To make an existing user a member of a group: 

sudo smbldap-groupmod -m username groupname 

The -m option can add more than one user at a time by listing them in comma-separated format. 

• To remove a user from a group: 

sudo smbldap-groupmod -x username groupname 

• To add a Samba machine account: 
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sudo smbldap-useradd -t 0 -w username 

Replace username with the name of the workstation. The -t 0 option creates the machine account 
without a delay, while the -w option specifies the user as a machine account. Also, note the add 
machine script parameter in /etc/samba/smb.conf was changed to use smbldap-useradd. 

There are utilities in the smbldap-tools package that were not covered here. Here is a complete list: 
smbldap-groupadd 3 ^ 

39 

smbldap-groupdel 

smbldap-groupmod 40 

smbldap-groupshow 41 

smbldap-passwd 42 

smbldap-populate 43 

smbldap-useradd 44 

smbldap-userdel 45 

smbldap-userinfo 46 

smbldap-userlist 41 

smbldap-usermod 4 ^ 

smbldap-usershow 49 

2.4. Resources 

• For more information on installing and configuring Samba see Chapter 18, Samba [p. 281 ] of 
this Ubuntu Server Guide. 

• There are multiple places where LDAP and Samba is documented in the upstream Samba HOWTO 
Collection 50 . 

• Regarding the above, see specifically the passdb section 51 . 

• Although dated (2007), the Linux Samba-OpenLDAP HOWTO 52 contains valuable notes. 

• The main page of the Samba Ubuntu community documentation 53 has a plethora of links to articles 
that may prove useful. 



38 

http://manpages.ubuntu.eom/manpages/en/man8/smbldap-groupadd.8.html 

39 

http://manpages.ubuntu.eom/manpages/en/man8/smbldap-groupdel.8.html 

40 http://manpages.ubuntu.eom/manpages/en/man8/smbldap-groupmod.8.html 

41 http://manpages.ubuntu.eom/manpages/en/man8/smbldap-groupshow.8.html 

42 http://manpages.ubuntu.eom/manpages/en/man8/smbldap-passwd.8.html 

43 http://manpages.ubuntu.eom/manpages/en/man8/smbldap-populate.8.html 
http://manpages.ubuntu.eom/manpages/en/man8/smbldap-useradd.8.html 

4 ^ http://manpages.ubuntu.eom/manpages/en/man8/smbldap-userdel.8.html 

4(3 http://manpages.ubuntu.eom/manpages/en/man8/smbldap-userinfo.8.html 

47 http://manpages.ubuntu.eom/manpages/en/man8/smbldap-userlist.8.html 
48 

http://manpages.ubuntu.eom/manpages/en/man8/smbldap-usermod.8.html 

49 

http://manpages.ubuntu.eom/manpages/en/man8/smbldap-usershow.8.html 

http://samba.org/samba/docs/man/Samba-HOWTO-Collection/ 

51 http://samba.org/samba/docs/man/Samba-HOWTO-Collection/passdb.html 
52 

http://download.gna.org/smbldap-tools/docs/samba-ldap-howto/ 

53 

https://help.ubuntu.eom/community/Samba#samba-ldap 
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3. Kerberos 

Kerberos is a network authentication system based on the principal of a trusted third party. The other 
two parties being the user and the service the user wishes to authenticate to. Not all services and 
applications can use Kerberos, but for those that can, it brings the network environment one step 
closer to being Single Sign On (SSO). 

This section covers installation and configuration of a Kerberos server, and some example client 
configurations. 

3.1. Overview 

If you are new to Kerberos there are a few terms that are good to understand before setting up 
a Kerberos server. Most of the terms will relate to things you may be familiar with in other 
environments: 

• Principal: any users, computers, and services provided by servers need to be defined as Kerberos 
Principals. 

• Instances: are used for service principals and special administrative principals. 

• Realms: the unique realm of control provided by the Kerberos installation. Think of it as the 
domain or group your hosts and users belong to. Convention dictates the realm should be in 
uppercase. By default, ubuntu will use the DNS domain converted to uppercase (EXAMPLE.COM) 
as the realm. 

• Key Distribution Center: (KDC) consist of three parts, a database of all principals, the 
authentication server, and the ticket granting server. For each realm there must be at least one KDC. 

• Ticket Granting Ticket: issued by the Authentication Server (AS), the Ticket Granting Ticket 
(TGT) is encrypted in the user's password which is known only to the user and the KDC. 

• Ticket Granting Server: (TGS) issues service tickets to clients upon request. 

• Tickets: confirm the identity of the two principals. One principal being a user and the other a 
service requested by the user. Tickets establish an encryption key used for secure communication 
during the authenticated session. 

• Keytab Files: are files extracted from the KDC principal database and contain the encryption key 
for a service or host. 

To put the pieces together, a Realm has at least one KDC, preferably more for redundancy, which 
contains a database of Principals. When a user principal logs into a workstation that is configured 
for Kerberos authentication, the KDC issues a Ticket Granting Ticket (TGT). If the user supplied 
credentials match, the user is authenticated and can then request tickets for Kerberized services from 
the Ticket Granting Server (TGS). The service tickets allow the user to authenticate to the service 
without entering another username and password. 
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3.2. Kerberos Server 

3.2.1. Installation 

For this discussion, we will create a MIT Kerberos domain with the following features (edit them to 
fit your needs): 

• Realm: EXAMPLE.COM 

• Primary KDC: kdcOl .example.com (192.168.0.1) 

• Secondary KDC: kdc02 .example .com ( 1 92 . 1 68 .0 .2) 

• User principal: steve 

• Admin principal: steve/admin 

It is strongly recommended that your network-authenticated users have their uid in a 
different range (say, starting at 5000) than that of your local users. 

Before installing the Kerberos server a properly configured DNS server is needed for your 
domain. Since the Kerberos Realm by convention matches the domain name, this section uses the 
EXAMPLE.COM domain configured in Section 2.3, "Primary Master" [p. 141 ] of the DNS 
documentation. 

Also, Kerberos is a time sensitive protocol. So if the local system time between a client machine 
and the server differs by more than five minutes (by default), the workstation will not be able 
to authenticate. To correct the problem all hosts should have their time synchronized using the 
same Network Time Protocol (NTP) server. For details on setting up NTP see Section 4, "Time 
Synchronisation with NTP" [p. 49]. 

The first step in creating a Kerberos Realm is to install the krb5-kdc and krb5-admin-server packages. 
From a terminal enter: 

sudo apt-get install krb5-kdc krb5-admin-server 

You will be asked at the end of the install to supply the hostname for the Kerberos and Admin servers, 
which may or may not be the same server, for the realm. 

By default the realm is created from the KDC's domain name. 



Next, create the new realm with the kdb5_newrealm utility: 

sudo krb5_newrealm 

3.2.2. Configuration 

The questions asked during installation are used to configure the /etc/krb5 .conf file. If you need 
to adjust the Key Distribution Center (KDC) settings simply edit the file and restart the krb5-kdc 
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daemon. If you need to reconfigure Kerberos from scratch, perhaps to change the realm name, you 
can do so by typing 

sudo dpkg-reconf igure krb5-kdc 

1 . Once the KDC is properly running, an admin user — the admin principal — is needed. It is 

recommended to use a different username from your everyday username. Using the kadmin.local 
utility in a terminal prompt enter: 

sudo kadmin.local 

Authenticating as principal root/admin@EXAMPLE . COM with password, 
kadmin.local: addprinc steve/admin 

WARNING: no policy specified for steve/admin@EXAMPLE . COM; defaulting to no policy 
Enter password for principal " steve/admin@EXAMPLE . COM" : 
Re-enter password for principal " steve/admin@EXAMPLE . COM" : 
Principal " steve/ admin@EXAMPLE . COM" created, 
kadmin.local: quit 

In the above example steve is the Principal, /admin is an Instance, and @EXAMPLE .COM 
signifies the realm. The "every day" Principal, a.k.a. the user principal, would be 
steve@EXAMPLE.COM, and should have only normal user rights. 




Replace EXAMPLE.COM and steve with your Realm and admin username. 



2. Next, the new admin user needs to have the appropriate Access Control List (ACL) permissions. 
The permissions are configured in the /etc/krb5kdc/kadm5 .acl file: 



steve/admin@EXAMPLE . COM * 

This entry grants steve/admin the ability to perform any operation on all principals in the realm. 
You can configure principals with more restrictive privileges, which is convenient if you need an 
admin principal that junior staff can use in Kerberos clients. Please see the kadm5.acl man page 
for details. 

3. Now restart the krb5-admin-server for the new ACL to take affect: 

sudo service krb5-admin-server restart 

4. The new user principal can be tested using the kinit utility: 

kinit steve/admin 

steve/admin@EXAMPLE . COM ' s Password : 

After entering the password, use the klist utility to view information about the Ticket Granting 
Ticket (TGT): 
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klist 

Credentials cache: FILE : /tmp/krb5cc_l 000 

Principal : steve/admin@EXAMPLE . COM 

Issued Expires Principal 

Jul 13 17:53:34 Jul 14 03:53:34 krbtgt/EXAMPLE .COM@EXAMPLE.COM 

Where the cache filename krb5cc_iooo is composed of the prefix krb5cc_ and the user id (uid), 
which in this case is 1000. You may need to add an entry into the /etc/hosts for the KDC so the 
client can find the KDC. For example: 

192.168.0.1 kdc01.example.com kdcOl 

Replacing 192.168.0.1 with the IP address of your KDC. This usually happens when you have a 
Kerberos realm encompassing different networks separated by routers. 

5. The best way to allow clients to automatically determine the KDC for the Realm is using DNS 
SRV records. Add the following to /etc/named/db. example. com: 

_kerberos._udp.EXAMPLE.COM. IN SRV 1 0 88 kdc01.example.com. 

_kerberos._tcp.EXAMPLE.COM. IN SRV 1 0 88 kdc01.example.com. 

_kerberos._udp.EXAMPLE.COM. IN SRV 10 0 88 kdc02.example.com. 

_kerberos._tcp.EXAMPLE.COM. IN SRV 10 0 88 kdc02.example.com. 

_kerberos-adm._tcp.EXAMPLE.COM. IN SRV 1 0 749 kdc01.example.com. 

_kpasswd._udp.EXAMPLE.COM. IN SRV 1 0 464 kdc01.example.com. 




Replace EXAMPLE.COM, kdcOl , and kdc02 with your domain name, primary KDC, 
and secondary KDC. 



See Chapter 8, Domain Name Service (DNS) [p. 138] for detailed instructions on setting up 
DNS. 

Your new Kerberos Realm is now ready to authenticate clients. 

3.3. Secondary KDC 

Once you have one Key Distribution Center (KDC) on your network, it is good practice to have a 
Secondary KDC in case the primary becomes unavailable. Also, if you have Kerberos clients that are 
in different networks (possibly separated by routers using NAT) , it is wise to place a secondary KDC 
in each of those networks. 

1. First, install the packages, and when asked for the Kerberos and Admin server names enter the 
name of the Primary KDC: 

sudo apt-get install krb5-kdc krb5-admin-server 

2. Once you have the packages installed, create the Secondary KDC's host principal. From a 
terminal prompt, enter: 
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kadmin -q "addprinc -randkey host/kdc02 . example . com" 

a— I After, issuing any kadmin commands you will be prompted for your usernamel 
admin@EXAMPLE.COM principal password. 

3. Extract the key tab file: 

kadmin -q "ktadd -norandkey -k keytab.kdc02 host /kdc02 . example . com" 

4. There should now be a keytab.kdc02 in the current directory, move the file to /etc/ 
krb5 . keytab: 

sudo mv keytab. kdc02 /etc/krb5 . keytab 




If the path to the keytab. kdc 02 file is different adjust accordingly. 



Also, you can list the principals in a Keytab file, which can be useful when troubleshooting, 
using the klist utility: 

sudo klist -k /etc/krb5 . keytab 

The -k option indicates the file is a keytab file. 

5. Next, there needs to be a kpropd . aci file on each KDC that lists all KDCs for the Realm. For 
example, on both primary and secondary KDC, create /etc/krb5kdc/kpropd.acl: 

host/kdcO 1 . example . com@ EXAMPLE . COM 
host/kdc02 . example . com@ EXAMPLE . COM 

6. Create an empty database on the Secondary KDC: 

sudo kdb5_util -s create 

7. Now start the kpropd daemon, which listens for connections from the kprop utility, kprop is used 
to transfer dump files: 

sudo kpropd -S 

8. From a terminal on the Primary KDC, create a dump file of the principal database: 

sudo kdb5_util dump /var/lib/krb5kdc/dump 

9. Extract the Primary KDCs keytab file and copy it to /etc/krb5 . keytab: 

kadmin -q "ktadd -k keytab. kdcOl host/kdcOl . example . com" 
sudo mv keytab. kdcOl /etc/krb5 . keytab 
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Make sure there is a host for kdcOl .example .com before extracting the Keytab. 



10. Using the kprop utility push the database to the Secondary KDC: 

sudo kprop -r EXAMPLE.COM -f /var/lib/krb5kdc/dump kdc02.example.com 




There should be a SUCCEEDED message if the propagation worked. If there is an error 
message check /var/iog/syslog on the secondary KDC for more information. 



You may also want to create a cron job to periodically update the database on the Secondary 
KDC. For example, the following will push the database every hour (note the long line has been 
split to fit the format of this document): 

# m h dom mon dow command 

0 * * * * /usr/sbin/kdb5_util dump /var/lib/krb5kdc/dump && 
/usr/sbin/kprop -r EXAMPLE.COM -f /var/lib/krb5kdc/dump kdc02.example.com 

1 1 . Back on the Secondary KDC, create a stash file to hold the Kerberos master key: 

sudo kdb5_util stash 

12. Finally, start the krb5-kdc daemon on the Secondary KDC: 

sudo service krb5-kdc start 

The Secondary KDC should now be able to issue tickets for the Realm. You can test this by stopping 
the krb5-kdc daemon on the Primary KDC, then by using kinit to request a ticket. If all goes well you 
should receive a ticket from the Secondary KDC. Otherwise, check /var/log/syslog and /var/log/ 
auth. log in the Secondary KDC. 

3.4. Kerberos Linux Client 

This section covers configuring a Linux system as a Kerberos client. This will allow access to any 
kerberized services once a user has successfully logged into the system. 

3.4.1. Installation 

In order to authenticate to a Kerberos Realm, the krb5-user and libpam-krb5 packages are needed, 
along with a few others that are not strictly necessary but make life easier. To install the packages 
enter the following in a terminal prompt: 

sudo apt-get install krb5-user libpam-krb5 libpam-ccreds auth-client-conf ig 

The auth-client-config package allows simple configuration of PAM for authentication from multiple 
sources, and the libpam-ccreds will cache authentication credentials allowing you to login in case 
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the Key Distribution Center (KDC) is unavailable. This package is also useful for laptops that may 
authenticate using Kerberos while on the corporate network, but will need to be accessed off the 
network as well. 

3.4.2. Configuration 

To configure the client in a terminal enter: 



sudo dpkg-reconf Igure krb5-config 

You will then be prompted to enter the name of the Kerberos Realm. Also, if you don't have DNS 
configured with Kerberos SR V records, the menu will prompt you for the hostname of the Key 
Distribution Center (KDC) and Realm Administration server. 

The dpkg-reconfigure adds entries to the /etc/krb5 .conf file for your Realm. You should have 
entries similar to the following: 



[libdefaults] 

def ault_realm = EXAMPLE.COM 

[ realms ] 

EXAMPLE.COM = { 

kdc = 192 . 168 . 0 . 1 
admin_server = 192.168.0.1 

} 

If you set the uid of each of your network-authenticated users to start at 5000, as suggested 
in Section 3.2.1, "Installation" [p. 124], you can then tell pam to only try to authenticate 
using Kerberos users with uid > 5000: 



# Kerberos should only be applied to ldap/kerberos users, not local ones, 
for i in common-auth common-session common-account common-password; do 
sudo sed -i -r \ 

-e ' s/pam_krb5 . so minimum_uid=1000/pam_krb5 . so minimum_uid=5000/ ' \ 
/etc/pam.d/$i 
done 

This will avoid being asked for the (non-existent) Kerberos password of a locally 
authenticated user when changing its password using passwd. 

You can test the configuration by requesting a ticket using the kinit utility. For example: 



kinit steve@EXAMPLE.COM 

Password for steve@EXAMPLE.COM: 

When a ticket has been granted, the details can be viewed using klist: 
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klist 

Ticket cache: FILE : /tmp/krb5cc_1000 
Default principal: steve@EXAMPLE.COM 



Valid starting Expires Service principal 

07/24/08 05:18:56 07/24/08 15:18:56 krbtgt/EXAMPLE . COM@EXAMPLE.COM 
renew until 07/25/08 05:18:57 



Kerberos 4 ticket cache: /tmp/tktlOOO 
klist: You have no tickets cached 

Next, use the auth-client-config to configure the libpam-krb5 module to request a ticket during login: 

sudo auth-client-config -a -p kerberosexample 

You will should now receive a ticket upon successful login authentication. 

3.5. Resources 

• For more information on MIT's version of Kerberos, see the MIT Kerberos 54 site. 

• The Ubuntu Wiki Kerberos 55 page has more details. 

• O'Reilly's Kerberos: The Definitive Guide 56 is a great reference when setting up Kerberos. 

• Also, feel free to stop by the #ubuntu-server and #kerberos IRC channels on Freenode 51 if you 
have Kerberos questions. 



http://web.mit.edu/Kerberos/ 
https://help.ubuntu.com/community/Kerberos 
http://oreilly.com/catalog/9780596004033/ 
http://freenode.net/ 
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4. Kerberos and LDAP 

Most people will not use Kerberos by itself; once an user is authenticated (Kerberos), we need to 
figure out what this user can do (authorization). And that would be the job of programs such as 
LDAP. 

Replicating a Kerberos principal database between two servers can be complicated, and adds an 
additional user database to your network. Fortunately, MIT Kerberos can be configured to use an 
LDAP directory as a principal database. This section covers configuring a primary and secondary 
kerberos server to use OpenLDAP for the principal database. 




The examples presented here assume MIT Kerberos and OpenLDAP. 



4.1 . Configuring OpenLDAP 

First, the necessary schema needs to be loaded on an OpenLDAP server that has network connectivity 
to the Primary and Secondary KDCs. The rest of this section assumes that you also have LDAP 
replication configured between at least two servers. For information on setting up OpenLDAP see 
Section 1, "OpenLDAP Server" [p. 91]. 

It is also required to configure OpenLDAP for TLS and SSL connections, so that traffic between the 
KDC and LDAP server is encrypted. See Section 1.8, "TLS" [p. 105] for details. 

cn=admin,cn=conf ig is a user we created with rights to edit the ldap database. Many times 
it is the RootDN. Change its value to reflect your setup. 

• To load the schema into LDAP, on the LDAP server install the krb5-kdc-ldap package. From a 
terminal enter: 



sudo apt-get install krb5-kdc-ldap 

• Next, extract the kerberos . schema . gz file: 



sudo gzip -d /usr/share/doc/krb5-kdc-ldap/kerberos . schema. gz 

sudo cp /usr/share/doc/krb5-kdc-ldap/kerberos . schema /etc/ldap/schema/ 

• The kerberos schema needs to be added to the cn=config tree. The procedure to add a new schema 
to slapd is also detailed in Section 1.4, "Modifying the slapd Configuration Database" [p. 96]. 

1 . First, create a configuration file named schema_convert . conf , or a similar descriptive name, 
containing the following lines: 



include /etc/ldap/schema/core . schema 
include /etc/ldap/schema/collective . schema 
include /etc/ldap/schema/corba . schema 
include /etc/ldap/schema/cosine . schema 
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include /etc/ldap/schema/duaconf . schema 

include /etc/ldap/schema/dyngroup . schema 

include /etc/ldap/schema/inetorgperson . schema 

include /etc/ldap/schema/ java. schema 

include /etc/ldap/schema/misc . schema 

include /etc/ldap/schema/nis . schema 

include /etc/ldap/schema/openldap . schema 

include /etc/ldap/schema/ppolicy . schema 

include /etc/ldap/schema/kerberos . schema 

2. Create a temporary directory to hold the LDIF files: 

mkdir /tmp/ldif_output 

3. Now use slapcat to convert the schema files: 

slapcat -f schema_convert.conf -F /tmp/ldif_output -nO -s \ 
"cn={12}kerberos,cn=schema,cn=conf ig" > /tmp/cn=kerberos . ldif 

Change the above file and path names to match your own if they are different. 

4. Edit the generated /tmp/cn\=kerberos . ldif file, changing the following attributes: 

dn : cn=kerberos , cn=schema , cn=conf ig 
cn: kerberos 

And remove the following lines from the end of the file: 

structuralObjectClass : olcSchemaConf ig 
entryUUID: 18ccd010-74 6b-102d-9fbe-37 60cca7 65dc 
creatorsName : cn=config 
createTimestamp: 20090111203515Z 

entryCSN: 20090 1 1 12035 15 . 326445Z#000000#000#000000 
modif iersName : cn=config 
modifyTimestamp: 20090111203515Z 

The attribute values will vary, just be sure the attributes are removed. 

5. Load the new schema with ldapadd: 

ldapadd -x -D cn=admin , cn=conf ig -W -f /tmp/cn\=kerberos . ldif 

6. Add an index for the krb5principalname attribute: 

ldapmodify -x -D cn=admin, cn=conf ig -W 
Enter LDAP Password: 
dn: olcDatabase={l}hdb,cn=config 
add: olcDblndex 

olcDblndex: krbPrincipalName eq,pres,sub 
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modifying entry "olcDatabase={ 1 }hdb, cn=conf ig" 
7. Finally, update the Access Control Lists (ACL): 

ldapmodif y -x -D cn=admin, cn=conf ig -W 
Enter LDAP Password: 
dn: olcDatabase={l}hdb,cn=config 
replace: olcAccess 

olcAccess: to attrs=userPassword , shadowLastChange , krbPrincipalKey by 
dn="cn=admin,dc=example,dc=com" write by anonymous auth by self write by * none 

add: olcAccess 

olcAccess: to dn.base="" by * read 
add: olcAccess 

olcAccess: to * by dn="cn=admin,dc=example,dc=com" write by * read 

modifying entry "olcDatabase={ 1 }hdb, cn=conf ig" 

That's it, your LDAP directory is now ready to serve as a Kerberos principal database. 

4.2. Primary KDC Configuration 

With OpenLDAP configured it is time to configure the KDC. 

• First, install the necessary packages, from a terminal enter: 

sudo apt-get install krb5-kdc krb5-admin-server krb5-kdc-ldap 

• Now edit /etc/krb5 . conf adding the following options to under the appropriate sections: 

[libdefaults] 

default_realm = EXAMPLE.COM 

[realms] 

EXAMPLE.COM = { 

kdc = kdc01.example.com 
kdc = kdc02.example.com 
admin_server = kdc01.example.com 
admin_server = kdc02.example.com 
def ault_domain = example.com 
database_module = openldap_ldapconf 

} 

[ domain_r ealm ] 

.example.com = EXAMPLE.COM 
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[dbdefaults] 

ldap_kerberos_container_dn = dc=example , dc=com 



[ dbmodules ] 

openldap_ldapconf = { 

db_library = kldap 

ldap_kdc_dn = "cn=admin, dc=example , dc=com" 



# this object needs to have read rights on 

# the realm container, principal container and realm sub-trees 
ldap_kadmind_dn = "cn=admin, dc=example , dc=com" 

# this object needs to have read and write rights on 

# the realm container, principal container and realm sub-trees 
ldap_service_password_f ile = /etc/krb5kdc/service . keyf ile 
ldap_servers = ldaps : //IdapO 1 . example . com ldaps : //ldap02 . example . com 
ldap_conns_per_server = 5 



Change example.com, dc=example,dc=com, cn= admin, dc= example, dc= com, and 
IdapOl .example .com to the appropriate domain, LDAP object, and LDAP server for your 
network. 

Next, use the kdb5_ldap_util utility to create the realm: 



sudo kdb5_ldap_util -D cn=admin,dc=example,dc=com create -subtrees \ 
dc=example,dc=com -r EXAMPLE.COM -s -H ldap: //IdapOl . example . com 

• Create a stash of the password used to bind to the LDAP server. This password is used by the 
ldap_kdc_dn and ldap_kadmin_dn options in /etc/krb5 .conf : 



sudo kdb5_ldap_util -D cn=admin,dc=example,dc=com stashsrvpw -f \ 
/etc /krb5kdc/ service . keyf ile cn=admin,dc=example,dc=com 

• Copy the CA certificate from the LDAP server: 



scp IdapOl : /etc/ssl/certs/cacert .pern . 
sudo cp cacert.pem /etc/ssl/certs 

And edit /etc/ldap/idap.conf to use the certificate: 



TLS_CACERT /etc/ssl/certs/cacert . pem 

i The certificate will also need to be copied to the Secondary KDC, to allow the connection 
to the LDAP servers using LDAPS. 
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You can now add Kerberos principals to the LDAP database, and they will be copied to any other 
LDAP servers configured for replication. To add a principal using the kadmin .local utility enter: 



sudo kadmin. local 

Authenticating as principal root/admin@EXAMPLE . COM with password. 

kadmin . local : addprinc -x dn="uid=steve,ou=people,dc=example,dc=com" steve 

WARNING: no policy specified for steve@EXAMPLE.COM; defaulting to no policy 
Enter password for principal "steve@EXAMPLE.COM": 
Re-enter password for principal "steve@EXAMPLE.COM": 
Principal "steve@EXAMPLE.COM" created. 

There should now be krbPrincipalName, krbPrincipalKey, krbLastPwdChange, and krbExtraData 
attributes added to the uid=steve,ou=people,dc=example,dc=com user object. Use the kinit and klist 
utilities to test that the user is indeed issued a ticket. 

If the user object is already created the -x dn= option is needed to add the Kerberos 
attributes. Otherwise a new principal object will be created in the realm subtree. 

4.3. Secondary KDC Configuration 

Configuring a Secondary KDC using the LDAP backend is similar to configuring one using the 
normal Kerberos database. 

1 . First, install the necessary packages. In a terminal enter: 

sudo apt-get install krb5-kdc krb5-admin-server krb5-kdc-ldap 

2. Next, edit /etc/krb5 .conf to use the LDAP backend: 



[libdefaults] 

default realm = EXAMPLE.COM 



[ realms ] 

EXAMPLE.COM = { 

kdc = kdc01.example.com 
kdc = kdc02.example.com 
admin_server = kdc01.example.com 
admin_server = kdc02.example.com 
def ault_domain = example . com 
database_module = openldap_ldapconf 



[ domain_r ealm ] 

.example.com = EXAMPLE.COM 
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[dbdefaults] 

ldap_kerberos_container_dn = dc=example , dc=com 

[ dbmodules ] 

openldap_ldapconf = { 

db_library = kldap 

ldap_kdc_dn = "cn=admin , dc=example , dc=com" 

# this object needs to have read rights on 

# the realm container, principal container and realm sub-trees 
ldap_kadmind_dn = "cn=admin , dc=example , dc=com" 

# this object needs to have read and write rights on 

# the realm container, principal container and realm sub-trees 
ldap_service_password_f ile = /etc/krb5kdc/service . keyf ile 
ldap_servers = ldaps : //IdapO 1 . example . com ldaps : //ldap02 . example . com 
ldap_conns_per_server = 5 

} 

3. Create the stash for the LDAP bind password: 

sudo kdb5_ldap_util -D cn=admin,dc=example,dc=com stashsrvpw -f \ 
/etc /krb5kdc/ service . keyf ile cn=admin,dc=example,dc=com 

4. Now, on the Primary KDC copy the /etc/krb5kdc/ . k5 . example . com Master Key stash to 
the Secondary KDC. Be sure to copy the file over an encrypted connection such as scp, or on 
physical media. 

sudo scp / etc/krb5kdc/ . k5 . EXAMPLE . COM steve@kdc02 . example . com: - 
sudo mv .k5.EXAMPLE.COM /etc/krb5kdc/ 




Again, replace EXAMPLE.COM with your actual realm. 



5. Back on the Secondary KDC, (re)start the ldap server only, 

sudo service slapd restart 

6. Finally, start the krb5-kdc daemon: 

sudo service krb5-kdc start 

7. Verify the two ldap servers (and kerberos by extension) are in sync. 

You now have redundant KDCs on your network, and with redundant LDAP servers you should be 
able to continue to authenticate users if one LDAP server, one Kerberos server, or one LDAP and one 
Kerberos server become unavailable. 
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4.4. Resources 

• The Kerberos Admin Guide 5 * has some additional details. 

• For more information on kdb5_ldap_util see Section 5.6 59 and the kdb5_ldap_util man page 

• Another useful link is the krb5 .conf man page 61 . 

• Also, see the Kerberos and LDAP 62 Ubuntu wiki page. 



http://web.mit.edu/Kerberos/krb5-l .6/krb5-1.6.3/doc/krb5-admin.html#Configuring-Kerberos-with-OpenLDAP-back_002dend 
http://web.mit.edu/Kerberos/krb5-l .6/krb5-1.6.3/doc/krb5-admin.html#Global-Operations-on-the-Kerberos-LDAP-Database 
http://manpages.ubuntu.eom/manpages/trusty/en/man8/kdb5_ldap_util.8.html 
http://manpages.ubuntu.eom/manpages/trusty/en/man5/krb5.conf.5.html 
https://help.ubuntu.eom/community/Kerberos#kerberos-ldap 
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Domain Name Service (DNS) is an Internet service that maps IP addresses and fully qualified domain 
names (FQDN) to one another. In this way, DNS alleviates the need to remember IP addresses. 
Computers that run DNS are called name servers. Ubuntu ships with BIND (Berkley Internet Naming 
Daemon), the most common program used for maintaining a name server on Linux. 
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1. Installation 

At a terminal prompt, enter the following command to install dns: 
sudo apt-get install bind9 

A very useful package for testing and troubleshooting DNS issues is the dnsutils package. Very often 
these tools will be installed already, but to check and/or install dnsutils enter the following: 

sudo apt-get install dnsutils 
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2. Configuration 

There are many ways to configure BIND9. Some of the most common configurations are a caching 
nameserver, primary master, and as a secondary master. 

• When configured as a caching nameserver BIND9 will find the answer to name queries and 
remember the answer when the domain is queried again. 

• As a primary master server BIND9 reads the data for a zone from a file on it's host and is 
authoritative for that zone. 

• In a secondary master configuration BIND9 gets the zone data from another nameserver 
authoritative for the zone. 

2.1 . Overview 

The DNS configuration files are stored in the /etc/bind directory. The primary configuration file is / 
etc /bind/named. conf. 

The include line specifies the filename which contains the DNS options. The directory line in the / 
etc/bind/named. conf .options file tells DNS where to look for files. All files BIND uses will be 
relative to this directory. 

The file named /etc/bind/db.root describes the root nameservers in the world. The servers change 
over time, so the /etc/bind/db.root file must be maintained now and then. This is usually done 
as updates to the bind9 package. The zone section defines a master server, and it is stored in a file 
mentioned in the file option. 

It is possible to configure the same server to be a caching name server, primary master, and secondary 
master. A server can be the Start of Authority (SOA) for one zone, while providing secondary service 
for another zone. All the while providing caching services for hosts on the local LAN. 

2.2. Caching Nameserver 

The default configuration is setup to act as a caching server. All that is required is simply adding the 
IP Addresses of your ISP's DNS servers. Simply uncomment and edit the following in /etc/bind/ 
named . conf . options: 



forwarders { 

1.2.3.4; 
5.6.7.8; 

}; 



*— I Replace 1.2.3.4 and 5.6.7.8 with the IP Adresses of actual nameservers. 

K>tt 



Now restart the DNS server, to enable the new configuration. From a terminal prompt: 
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sudo service bind9 restart 

See Section 3.1.2, "dig" [p. 146] for information on testing a caching DNS server. 

2.3. Primary Master 

In this section BIND9 will be configured as the Primary Master for the domain example.com. Simply 
replace example.com with your FQDN (Fully Qualified Domain Name). 

2.3.1 . Forward Zone File 

To add a DNS zone to BIND9, turning BIND9 into a Primary Master server, the first step is to edit / 
etc/bind/named . conf . local: 

zone "example.com" { 
type master; 

file "/etc/bind/db. example. com" ; 

}; 

(Note, if bind will be receiving automatic updates to the file as with DDNS, then use /var/iib/bind/ 
db.exampie.com rather than /etc/bind/db. example. com both here and in the copy command below.) 

Now use an existing zone file as a template to create the /etc/bind/db . example . com file: 
sudo cp /etc/bind/db. local /etc/bind/db. example. com 

Edit the new zone file /etc/bind/db. example, com change localhost. to the FQDN of your 
server, leaving the additional "." at the end. Change 127.0.0.1 to the nameserver's IP Address and 
root .localhost to a valid email address, but with a "." instead of the usual "@" symbol, again leaving 
the " ." at the end. Change the comment to indicate the domain that this file is for. 

Create an A record for the base domain, example.com. Also, create an A record for ns.example.com, 
the name server in this example: 



BIND data file for example.com 



$TTL 604800 

§ IN SOA 



example.com. root.example.com. ( 



IN 



2 

604800 
86400 
2419200 

604800 ) 
192 .168.1.10 



Serial 
Refresh 
Retry 
Expire 

Negative Cache TTL 



IN 



NS 



ns . example . com . 
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@ 


IN 


A 


U 


32 


168 


. 1 


10 


8 


IN 


AAAA 




1 








ns 


IN 


A 


U 


32 


168 


. 1 


10 



You must increment the Serial Number every time you make changes to the zone file. If you make 
multiple changes before restarting BIND9, simply increment the Serial once. 

Now, you can add DNS records to the bottom of the zone file. See Section 4.1, "Common Record 
Types" [p. 150] for details. 

Many admins like to use the last date edited as the serial of a zone, such as 2012010100 
which is yyyymmddss (where ss is the Serial Number) 

Once you have made changes to the zone file BIND9 needs to be restarted for the changes to take 
effect: 

sudo service bind9 restart 

2.3.2. Reverse Zone File 

Now that the zone is setup and resolving names to IP Adresses a Reverse zone is also required. A 
Reverse zone allows DNS to resolve an address to a name. 

Edit /etc/bind/named .conf .local and add the following: 

zone " 1 . 168 . 192 . in-addr . arpa" { 
type master; 

file "/etc/bind/db. 192" ; 

}; 

Replace 1.168.192 with the first three octets of whatever network you are using. Also, 
name the zone file /etc/bind/db. 192 appropriately. It should match the first octet of your 
network. 

Now create the /etc/bind/db. 192 file: 

sudo cp /etc/bind/db. 127 /etc/bind/db. 192 

Next edit /etc/bind/db. 192 changing the basically the same options as /etc/bind/db. example. com: 



BIND reverse data file for local 192 . 168 . 1 . XXX net 



$TTL 604800 

8 IN SOA 



ns.example.com. root.example.com. ( 



2 

604800 
86400 



Serial 

Refresh 

Retry 
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2419200 



604800 ) 



Expire 

Negative Cache TTL 



@ 



IN 



NS 



ns . 



10 



IN 



PTR 



ns . example . com . 



The Serial Number in the Reverse zone needs to be incremented on each change as well. For each 
A record you configure in /etc/bind/db . example . com, that is for a different address, you need to 
create a PTR record in /etc/bind/db. 192. 

After creating the reverse zone file restart BIND9: 
sudo service bind9 restart 

2.4. Secondary Master 

Once a Primary Master has been configured a Secondary Master is needed in order to maintain the 
availability of the domain should the Primary become unavailable. 

First, on the Primary Master server, the zone transfer needs to be allowed. Add the allow-transfer 
option to the example Forward and Reverse zone definitions in /etc/bind/named. conf . local: 

zone "example.com" { 
type master; 
file " /etc/bind/db . example . com" ; 

allow-transfer { 192.168.1.11; }; 

}; 

zone " 1 . 168 . 192 . in-addr . arpa" { 



Restart BIND9 on the Primary Master: 
sudo service bind9 restart 

Next, on the Secondary Master, install the bind9 package the same way as on the Primary. Then edit 
the /etc/bind/named . conf . local and add the following declarations for the Forward and Reverse 
zones: 

zone "example.com" { 
type slave; 



type master; 

file "/etc/bind/db. 192" ; 
allow-transfer { 192.168.1.11; }; 



}; 




Replace 192.168.1 .11 with the IP Address of your Secondary nameserver. 
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file "db.example.com"; 
masters { 192.168.1.10; }; 

}; 

zone " 1 . 168 . 192 . in-addr . arpa" { 
type slave; 

file "db.192"; 

masters { 192.168.1.10; }; 

}; 

*— I Replace 192.168.1 .10 with the IP Address of your Primary nameserver. 



Restart BIND9 on the Secondary Master: 



sudo service bind9 restart 

In /var/iog/syslog you should see something similar to (some lines have been split to fit the format 
of this document): 



client 192 . 168 . 1 . 10#39448 : received notify for zone ' 1 . 168 . 192 . in-addr . arpa ' 

zone 1 . 168 . 192 . in-addr . arpa/IN : Transfer started. 

transfer of ' 100 . 18 . 172 . in-addr . arpa/IN ' from 192 . 168 . 1 . 10#53 : 

connected using 192 . 168 . 1 . 11#37531 
zone 1 . 168 . 192 . in-addr . arpa/IN : transferred serial 5 
transfer of ' 100 . 18 . 172 . in-addr . arpa/IN ' from 192 . 168 . 1 . 10#53 : 

Transfer completed: 1 messages, 
6 records, 212 bytes, 0.002 sees (106000 bytes/sec) 
zone 1 . 168 . 192 . in-addr . arpa/IN : sending notifies (serial 5) 

client 192 . 168 . 1 . 10#20329 : received notify for zone 'example.com' 
zone example.com/IN: Transfer started. 

transfer of 'example.com/lN' from 192 . 168 . 1 . 10#53 : connected using 192 . 168 . 1 . 11#38577 
zone example.com/IN: transferred serial 5 

transfer of 'example.com/lN' from 192 . 168 . 1 . 10#53 : Transfer completed: 1 messages, 
8 records, 225 bytes, 0.002 sees (112500 bytes/sec) 

Note: A zone is only transferred if the Serial Number on the Primary is larger than the 
one on the Secondary. If you want to have your Primary Master DNS notifying Secondary 
DNS Servers of zone changes, you can add also-notify { ipaddress; }; in to /etc/bind/ 
named . conf . local as shown in the example below: 



zone "example.com" { 
type master; 

file " /etc/bind/db . example . com" ; 
allow-transfer { 192.168.1.11; }; 
also-notify { 192.168.1.11; }; 

}; 
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zone " 1 . 168 . 192 . in-addr . arpa" { 
type master; 

file "/etc/bind/db.192"; 
allow-transfer { 192.168.1.11; }; 
also-notify { 192.168.1.11; }; 

}; 



The default directory for non-authoritative zone files is /var /cache/bind/. This directory 
is also configured in App Armor to allow the named daemon to write to it. For more 
information on AppArmor see Section 4, "AppArmor" [p. 166]. 
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3. Troubleshooting 

This section covers ways to help determine the cause when problems happen with DNS and BIND9. 

3.1 . Testing 

3.1.1. resolv.conf 

The first step in testing BIND9 is to add the nameserver's IP Address to a hosts resolver. The 
Primary nameserver should be configured as well as another host to double check things. Refer to 
Section 13.1, "DNS Client Configuration" [p. 37] for details on adding nameserver addresses to your 
network clients, and afterwards check that the file /etc/resoiv.conf contains (for this example): 

nameserver 192.168.1.10 
nameserver 192.168.1.11 

Nameservers that listen at 127.* are responsible for adding their own IP addresses to resolv.conf 
(using resolvconf). This is done via the file /etc/def ault/bind9 by changing the line 
RESOLVCONF=no to RESOLVCONF=yes. 




You should also add the IP Address of the Secondary nameserver in case the Primary 
becomes unavailable. 



3.1.2. dig 

If you installed the dnsutils package you can test your setup using the DNS lookup utility dig: 

• After installing BIND9 use dig against the loopback interface to make sure it is listening on port 53. 
From a terminal prompt: 

dig -x 127.0.0.1 

You should see lines similar to the following in the command output: 
;; Query time: 1 msec 

;; SERVER: 192 . 168 . 1 . 10#53 ( 192 . 168 . 1 . 10 ) 

• If you have configured BIND9 as a Caching nameserver "dig" an outside domain to check the 
query time: 

dig ubuntu.com 

Note the query time toward the end of the command output: 
;; Query time: 4 9 msec 
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After a second dig there should be improvement: 

;; Query time: 1 msec 

3.1.3. ping 

Now to demonstrate how applications make use of DNS to resolve a host name use the ping utility to 
send an ICMP echo request. From a terminal prompt enter: 

ping example.com 

This tests if the nameserver can resolve the name ns.example.com to an IP Address. The command 
output should resemble: 

PING ns.example.com (192.168.1.10) 56(84) bytes of data. 

64 bytes from 192.168.1.10: icmp_seq=l ttl=64 time=0.800 ms 

64 bytes from 192.168.1.10: icmp_seq=2 ttl=64 time=0.813 ms 

3.1.4. named-checkzone 

A great way to test your zone files is by using the named-checkzone utility installed with the bind9 
package. This utility allows you to make sure the configuration is correct before restarting BIND9 and 
making the changes live. 

• To test our example Forward zone file enter the following from a command prompt: 

named-checkzone example.com /etc/bind/db. example. com 

If everything is configured correctly you should see output similar to: 

zone example.com/lN: loaded serial 6 
OK 

• Similarly, to test the Reverse zone file enter the following: 

named-checkzone 1 . 168 . 192 . in-addr . arpa /etc/bind/db. 192 

The output should be similar to: 

zone 1 . 168 . 192 . in-addr . arpa/lN : loaded serial 3 
OK 

l%— I The Serial Number of your zone file will probably be different. 
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3.2. Logging 

BIND9 has a wide variety of logging configuration options available. There are two main options. 
The channel option configures where logs go, and the category option determines what information to 
log. 

If no logging option is configured the default option is: 
logging { 

category default { def ault_syslog; def ault_debug; }; 
category unmatched { null; }; 

}; 

This section covers configuring BIND9 to send debug messages related to DNS queries to a separate 
file. 

• First, we need to configure a channel to specify which file to send the messages to. Edit /etc/ 
bind/named . conf . local and add the following: 

logging { 

channel query.log { 

file " /var/log/query . log" ; 
severity debug 3 ; 

}; 

}; 

• Next, configure a category to send all DNS queries to the query file: 



logging { 

channel query.log { 

file " /var/log/query . log" ; 
severity debug 3 ; 

}; 

category queries { query . log; }; 

}; 

|— I Note: the debug option can be set from 1 to 3. If a level isn't specified level 1 is the default. 



• Since the named daemon runs as the bind user the /var/log/query . log file must be created and 
the ownership changed: 

sudo touch /var/log/query . log 
sudo chown bind /var/log/query . log 

• Before named daemon can write to the new log file the AppArmor profile must be updated. First, 
edit /etc/apparmor . d/usr . sbin . named and add: 
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/var/log/query . log w, 
Next, reload the profile: 

cat /etc/apparmor .d/usr. sbin. named | sudo apparmor_parser -r 

For more information on App Armor see Section 4, "AppArmor" [p. 166] 
• Now restart BIND9 for the changes to take effect: 

sudo service bind9 restart 

You should see the file /var/log/query. log fill with query information. This is a simple 
example of the BIND9 logging options. For coverage of advanced options see Section 4.2, "More 
Information" [p. 150]. 
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4. References 

4.1 . Common Record Types 

This section covers some of the most common DNS record types. 

• A record: This record maps an IP Address to a hostname. 

www IN A 192.168.1.12 

• CNAME record: Used to create an alias to an existing A record. You cannot create a CNAME 
record pointing to another CNAME record. 

web IN CNAME www 

• MX record: Used to define where email should be sent to. Must point to an A record, not a 
CNAME. 

IN MX 1 mail.example.com. 
mail IN A 192.168.1.13 

• NS record: Used to define which servers serve copies of a zone. It must point to an A record, not a 
CNAME. This is where Primary and Secondary servers are defined. 

IN NS ns.example.com. 

IN NS ns2.example.com. 

ns IN A 192.168.1.10 

ns2 IN A 192.168.1.11 

4.2. More Information 

• The BIND9 Server HOWTO 1 in the Ubuntu Wiki has a lot of useful information. 

• The DNS HOWTO 2 at The Linux Documentation Project also has lots of information about 
configuring BIND9. 

• Bind9.net 3 has links to a large collection of DNS and BIND9 resources. 

• DNS and BIND 4 is a popular book now in it's fifth edition. There is now also a DNS and BIND on 
IPv6 5 book. 

• A great place to ask for BIND9 assistance, and get involved with the Ubuntu Server community, is 
the #ubuntu-server IRC channel on freenode 6 . 



https://help.ubuntu.com/community/BIND9ServerHowto 
2 http://www.tldp.org/HOWTO/DNS-HOWTO.html 
http :// w w w .bind9 .net/ 

4 http://shop.oreilly.com/product/9780596100575.do 

5 http://shop.oreilly.com/product/0636920020158.do 

6 http://freenode.net 
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Security should always be considered when installing, deploying, and using any type of computer 
system. Although a fresh installation of Ubuntu is relatively safe for immediate use on the Internet, it 
is important to have a balanced understanding of your systems security posture based on how it will 
be used after deployment. 

This chapter provides an overview of security related topics as they pertain to Ubuntu 14.04 LTS 
Server Edition, and outlines simple measures you may use to protect your server and network from 
any number of potential security threats. 
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1. User Management 



User management is a critical part of maintaining a secure system. Ineffective user and privilege 
management often lead many systems into being compromised. Therefore, it is important that you 
understand how you can protect your server through simple and effective user account management 
techniques. 

1.1. Where is root? 

Ubuntu developers made a conscientious decision to disable the administrative root account by default 
in all Ubuntu installations. This does not mean that the root account has been deleted or that it may 
not be accessed. It merely has been given a password which matches no possible encrypted value, 
therefore may not log in directly by itself. 

Instead, users are encouraged to make use of a tool by the name of sudo to carry out system 
administrative duties. Sudo allows an authorized user to temporarily elevate their privileges 
using their own password instead of having to know the password belonging to the root account. 
This simple yet effective methodology provides accountability for all user actions, and gives the 
administrator granular control over which actions a user can perform with said privileges. 

• If for some reason you wish to enable the root account, simply give it a password: 



Configurations with root passwords are not supported. 



sudo passwd 

Sudo will prompt you for your password, and then ask you to supply a new password for root as 
shown below: 



[sudo] password for username: (enter your own password) 
Enter new UNIX password: (enter a new password for root) 
Retype new UNIX password: (repeat new password for root) 

passwd: password updated successfully 

• To disable the root account password, use the following passwd syntax: 
sudo passwd -1 root 

However, to disable the root account itself, use the following command: 

usermod --expiredate 1 

• You should read more on Sudo by checking out it's man page: 



man sudo 
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By default, the initial user created by the Ubuntu installer is a member of the group "sudo" which is 
added to the file /etc/sudoers as an authorized sudo user. If you wish to give any other account full 
root access through sudo, simply add them to the sudo group. 

1.2. Adding and Deleting Users 

The process for managing local users and groups is straight forward and differs very little from most 
other GNU/Linux operating systems. Ubuntu and other Debian based distributions, encourage the use 
of the "adduser" package for account management. 

• To add a user account, use the following syntax, and follow the prompts to give the account a 
password and identifiable characteristics such as a full name, phone number, etc. 

sudo adduser username 

• To delete a user account and its primary group, use the following syntax: 

sudo deluser username 

Deleting an account does not remove their respective home folder. It is up to you whether or not 
you wish to delete the folder manually or keep it according to your desired retention policies. 

Remember, any user added later on with the same UID/GID as the previous owner will now have 
access to this folder if you have not taken the necessary precautions. 

You may want to change these UID/GID values to something more appropriate, such as the root 
account, and perhaps even relocate the folder to avoid future conflicts: 

sudo chown -R root: root /home/username/ 

sudo mkdir /home/archived_users/ 

sudo mv /home/username /home/archived_users/ 

• To temporarily lock or unlock a user account, use the following syntax, respectively: 

sudo passwd -1 username 
sudo passwd -u username 

• To add or delete a personalized group, use the following syntax, respectively: 

sudo addgroup groupname 
sudo delgroup groupname 

• To add a user to a group, use the following syntax: 
sudo adduser username groupname 
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1 .3 . User Profile Security 

When a new user is created, the adduser utility creates a brand new home directory named /home/ 
username, respectively. The default profile is modeled after the contents found in the directory of / 
etc /skel, which includes all profile basics. 

If your server will be home to multiple users, you should pay close attention to the user home 
directory permissions to ensure confidentiality. By default, user home directories in Ubuntu are 
created with world read/execute permissions. This means that all users can browse and access the 
contents of other users home directories. This may not be suitable for your environment. 

• To verify your current users home directory permissions, use the following syntax: 
Is -Id /home/username 

The following output shows that the directory /home/username has world readable permissions: 

drwxr-xr-x 2 username username 4096 2007-10-02 20:03 username 

• You can remove the world readable permissions using the following syntax: 

sudo chmod 07 50 /home/username 

Some people tend to use the recursive option (-R) indiscriminately which modifies all 
child folders and files, but this is not necessary, and may yield other undesirable results. 
The parent directory alone is sufficient for preventing unauthorized access to anything 
below the parent. 

A much more efficient approach to the matter would be to modify the adduser global default 
permissions when creating user home folders. Simply edit the file /etc/adduser .conf and modify 
the dir_mode variable to something appropriate, so that all new home directories will receive the 
correct permissions. 

DIR_MODE=0750 

After correcting the directory permissions using any of the previously mentioned techniques, verify 
the results using the following syntax: 

Is -Id /home/username 

The results below show that world readable permissions have been removed: 
drwxr-x 2 username username 4096 2007-10-02 20:03 username 
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1 .4. Password Policy 

A strong password policy is one of the most important aspects of your security posture. Many 
successful security breaches involve simple brute force and dictionary attacks against weak 
passwords. If you intend to offer any form of remote access involving your local password system, 
make sure you adequately address minimum password complexity requirements, maximum password 
lifetimes, and frequent audits of your authentication systems. 

1 .4.1 . Minimum Password Length 

By default, Ubuntu requires a minimum password length of 6 characters, as well as some basic 
entropy checks. These values are controlled in the file /etc/pam.d/common-password, which is 
outlined below. 



password [success=l def ault=ignore ] pam_unix.so obscure sha512 

If you would like to adjust the minimum length to 8 characters, change the appropriate variable to 
min=8. The modification is outlined below. 

password [success=l def ault=ignore ] pam_unix.so obscure sha512 minlen=8 

Basic password entropy checks and minimum length rules do not apply to the administrator 
using sudo level commands to setup a new user. 

1.4.2. Password Expiration 

When creating user accounts, you should make it a policy to have a minimum and maximum 
password age forcing users to change their passwords when they expire. 

• To easily view the current status of a user account, use the following syntax: 
sudo chage -1 username 

The output below shows interesting facts about the user account, namely that there are no policies 
applied: 



Last password change : Jan 20, 2008 

Password expires : never 

Password inactive : never 

Account expires : never 

Minimum number of days between password change : 0 

Maximum number of days between password change : 99999 

Number of days of warning before password expires : 7 

To set any of these values, simply use the following syntax, and follow the interactive prompts: 
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sudo chage username 

The following is also an example of how you can manually change the explicit expiration date (- 
E) to 01/31/2008, minimum password age (-m) of 5 days, maximum password age (-M) of 90 days, 
inactivity period (-1) of 5 days after password expiration, and a warning time period (-W) of 14 
days before password expiration. 

sudo chage -E 01/31/2011 -m 5 -M 90 -I 30 -W 14 username 

• To verify changes, use the same syntax as mentioned previously: 



sudo chage -1 username 

The output below shows the new policies that have been established for the account: 



Last password change : Jan 20, 2008 

Password expires : Apr 19, 2008 

Password inactive : May 19, 2008 

Account expires : Jan 31, 2008 

Minimum number of days between password change : 5 

Maximum number of days between password change : 90 

Number of days of warning before password expires : 14 



1 .5 . Other Security Considerations 

Many applications use alternate authentication mechanisms that can be easily overlooked by even 
experienced system administrators. Therefore, it is important to understand and control how users 
authenticate and gain access to services and applications on your server. 

1.5.1. SSH Access by Disabled Users 

Simply disabling/locking a user account will not prevent a user from logging into your server 
remotely if they have previously set up RSA public key authentication. They will still be able to 
gain shell access to the server, without the need for any password. Remember to check the users 
home directory for files that will allow for this type of authenticated SSH access, e.g. /home/ 
username/ . ssh/authorized_keys. 

Remove or rename the directory . ssh/ in the user's home folder to prevent further SSH authentication 
capabilities. 

Be sure to check for any established SSH connections by the disabled user, as it is possible they may 
have existing inbound or outbound connections. Kill any that are found. 



who |grep username (to get the pts/# terminal) 
sudo pkill -f pts/# 
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Restrict SSH access to only user accounts that should have it. For example, you may create a group 
called "sshlogin" and add the group name as the value associated with the AiiowGroups variable 
located in the file /etc/ssh/sshd_conf ig. 

AiiowGroups sshlogin 

Then add your permitted SSH users to the group "sshlogin" , and restart the SSH service. 

sudo adduser username sshlogin 
sudo service ssh restart 

1.5.2. External User Database Authentication 

Most enterprise networks require centralized authentication and access controls for all system 
resources. If you have configured your server to authenticate users against external databases, be 
sure to disable the user accounts both externally and locally, this way you ensure that local fallback 
authentication is not possible. 
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2. Console Security 

As with any other security barrier you put in place to protect your server, it is pretty tough to defend 
against untold damage caused by someone with physical access to your environment, for example, 
theft of hard drives, power or service disruption, and so on. Therefore, console security should be 
addressed merely as one component of your overall physical security strategy. A locked "screen door" 
may deter a casual criminal, or at the very least slow down a determined one, so it is still advisable to 
perform basic precautions with regard to console security. 

The following instructions will help defend your server against issues that could otherwise yield very 
serious consequences. 

2.1. Disable Ctrl+Alt+Delete 

First and foremost, anyone that has physical access to the keyboard can simply use the 
Ctrl+Alt+Delete key combination to reboot the server without having to log on. Sure, someone could 
simply unplug the power source, but you should still prevent the use of this key combination on a 
production server. This forces an attacker to take more drastic measures to reboot the server, and will 
prevent accidental reboots at the same time. 

• To disable the reboot action taken by pressing the Ctrl+Alt+Delete key combination, comment out 
the following line in the file /etc/init/control-alt-delete.conf . 

#exec shutdown -r now "Control-Alt-Delete pressed" 
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3. Firewall 

3.1. Introduction 

The Linux kernel includes the Netfilter subsystem, which is used to manipulate or decide the fate 
of network traffic headed into or through your server. All modern Linux firewall solutions use this 
system for packet filtering. 

The kernel's packet filtering system would be of little use to administrators without a userspace 
interface to manage it. This is the purpose of iptables. When a packet reaches your server, it will be 
handed off to the Netfilter subsystem for acceptance, manipulation, or rejection based on the rules 
supplied to it from userspace via iptables. Thus, iptables is all you need to manage your firewall if 
you're familiar with it, but many frontends are available to simplify the task. 

3.2. ufw - Uncomplicated Firewall 

The default firewall configuration tool for Ubuntu is ufw. Developed to ease iptables firewall 
configuration, ufw provides a user friendly way to create an IPv4 or IPv6 host-based firewall. 

ufw by default is initially disabled. From the ufw man page: 

" ufw is not intended to provide complete firewall functionality via its command interface, but 
instead provides an easy way to add or remove simple rules. It is currently mainly used for host-based 
firewalls. " 

The following are some examples of how to use ufw: 

• First, ufw needs to be enabled. From a terminal prompt enter: 

sudo ufw enable 

• To open a port (ssh in this example): 

sudo ufw allow 22 

• Rules can also be added using a numbered format: 

sudo ufw insert 1 allow 80 

• Similarly, to close an opened port: 

sudo ufw deny 22 

• To remove a rule, use delete followed by the rule: 

sudo ufw delete deny 22 

• It is also possible to allow access from specific hosts or networks to a port. The following example 
allows ssh access from host 192.168.0.2 to any ip address on this host: 
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sudo ufw allow proto tcp from 192.168.0.2 to any port 22 

Replace 192.168.0.2 with 192.168.0.0/24 to allow ssh access from the entire subnet. 

• Adding the —dry-run option to a ufw command will output the resulting rules, but not apply them. 
For example, the following is what would be applied if opening the HTTP port: 



sudo ufw --dry-run allow http 



♦filter 

: uf w-user-input - [0:0] 
: uf w-user-output - [0:0] 
: uf w-user-f orward - [0:0] 
: uf w-user-limit - [0:0] 
: uf w-user-limit-accept - [0:0] 
### RULES ### 

### tuple ### allow tcp 80 0.0.0.0/0 any 0.0.0.0/0 
-A ufw-user-input -p tcp — dport 80 -j ACCEPT 

### END RULES ### 
-A ufw-user-input -j RETURN 
-A ufw-user-output -j RETURN 
-A ufw-user-f orward -j RETURN 

-A uf w-user-limit -m limit --limit 3/minute -j LOG --log-prefix "[UFW LIMIT]: " 

-A ufw-user-limit -j REJECT 

-A ufw-user-limit-accept -j ACCEPT 

COMMIT 

Rules updated 

• ufw can be disabled by: 

sudo ufw disable 

• To see the firewall status, enter: 

sudo ufw status 

• And for more verbose status information use: 

sudo ufw status verbose 

• To view the numbered format: 



sudo ufw status numbered 



If the port you want to open or close is defined in /etc/services, you can use the port 
name instead of the number. In the above examples, replace 22 with ssh . 
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This is a quick introduction to using ufw. Please refer to the ufw man page for more information. 
3.2.1. ufw Application Integration 

Applications that open ports can include an ufw profile, which details the ports needed for the 
application to function properly. The profiles are kept in /etc/ufw/applications .d, and can be 
edited if the default ports have been changed. 

• To view which applications have installed a profile, enter the following in a terminal: 
sudo ufw app list 

• Similar to allowing traffic to a port, using an application profile is accomplished by entering: 

sudo ufw allow Samba 

• An extended syntax is available as well: 

ufw allow from 192.168.0.0/24 to any app Samba 

Replace Samba and 192.168.0.0124 with the application profile you are using and the IP range for 
your network. 

There is no need to specify the protocol for the application, because that information is 
detailed in the profile. Also, note that the app name replaces the port number. 

• To view details about which ports, protocols, etc are defined for an application, enter: 

sudo ufw app info Samba 

Not all applications that require opening a network port come with ufw profiles, but if you have 
profiled an application and want the file to be included with the package, please file a bug against the 
package in Launchpad. 



ubuntu-bug nameof package 

3.3. IP Masquerading 

The purpose of IP Masquerading is to allow machines with private, non-routable IP addresses on your 
network to access the Internet through the machine doing the masquerading. Traffic from your private 
network destined for the Internet must be manipulated for replies to be routable back to the machine 
that made the request. To do this, the kernel must modify the source IP address of each packet so that 
replies will be routed back to it, rather than to the private IP address that made the request, which 
is impossible over the Internet. Linux uses Connection Tracking (conntrack) to keep track of which 
connections belong to which machines and reroute each return packet accordingly. Traffic leaving 
your private network is thus "masqueraded" as having originated from your Ubuntu gateway machine. 
This process is referred to in Microsoft documentation as Internet Connection Sharing. 
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3.3.1. ufw Masquerading 

IP Masquerading can be achieved using custom ufw rules. This is possible because the current back- 
end for ufw is iptables-restore with the rules files located in /etc/ufw/*. rules. These files are a 
great place to add legacy iptables rules used without ufw, and rules that are more network gateway or 
bridge related. 

The rules are split into two different files, rules that should be executed before ufw command line 
rules, and rules that are executed after ufw command line rules. 

• First, packet forwarding needs to be enabled in ufw. Two configuration files will need to be 
adjusted, in /etc/default/ufw change the DEFAULT _FORWARD_POLICY to "ACCEPT": 

DEFAULT_FORWARD_POLICY= "ACCEPT " 

Then edit /etc/ufw/sysctl.conf and uncomment: 

net / ipv4 / ip_f orwar d= 1 

Similarly, for IPv6 forwarding uncomment: 

net /ipv6/conf /default /forwarding=l 

• Now we will add rules to the /etc/ufw/bef ore. rules file. The default rules only configure the 
filter table, and to enable masquerading the nat table will need to be configured. Add the following 
to the top of the file just after the header comments: 

# nat Table rules 
*nat 

:POSTROUTING ACCEPT [0:0] 

# Forward traffic from ethl through ethO . 

-A POSTROUTING -s 192.168.0.0/24 -o ethO -j MASQUERADE 

# don't delete the 'COMMIT' line or these nat table rules won't be processed 
COMMIT 

The comments are not strictly necessary, but it is considered good practice to document your 
configuration. Also, when modifying any of the rules files in /etc/ufw, make sure these lines are 
the last line for each table modified: 

# don't delete the 'COMMIT' line or these rules won't be processed 
COMMIT 

For each Table a corresponding COMMIT statement is required. In these examples only the nat and 
filter tables are shown, but you can also add rules for the raw and mangle tables. 
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In the above example replace ethO, ethl , and 192.168.0.0/24 with the appropriate 
interfaces and IP range for your network. 

Finally, disable and re-enable ufw to apply the changes: 



sudo ufw disable && sudo ufw enable 

IP Masquerading should now be enabled. You can also add any additional FORWARD rules to the 
/etc/ufw/bef ore. rules. It is recommended that these additional rules be added to the ufw-before- 
forward chain. 

3.3.2. iptables Masquerading 

iptables can also be used to enable Masquerading. 

• Similar to ufw, the first step is to enable IPv4 packet forwarding by editing /etc/sysctl . conf and 
uncomment the following line 

net . ipv4 . ip_f orward= 1 

If you wish to enable IPv6 forwarding also uncomment: 



net . ipv6 . conf . default . f orwarding=l 
• Next, execute the sysctl command to enable the new settings in the configuration file: 



sudo sysctl -p 

• IP Masquerading can now be accomplished with a single iptables rule, which may differ slightly 
based on your network configuration: 



sudo iptables -t nat -A POSTROUTING -s 192.168.0.0/16 -o pppO -j MASQUERADE 

The above command assumes that your private address space is 192.168.0.0/16 and that your 
Internet-facing device is pppO. The syntax is broken down as follows: 

• -t nat — the rule is to go into the nat table 

• -A POSTROUTING - the rule is to be appended (-A) to the POSTROUTING chain 

• -s 192.168.0.0/16 — the rule applies to traffic originating from the specified address space 

• -o pppO — the rule applies to traffic scheduled to be routed through the specified network device 

• -j MASQUERADE - traffic matching this rule is to "jump" (-j) to the MASQUERADE target to 
be manipulated as described above 

• Also, each chain in the filter table (the default table, and where most or all packet filtering occurs) 
has a default policy of ACCEPT, but if you are creating a firewall in addition to a gateway device, 
you may have set the policies to DROP or REJECT, in which case your masqueraded traffic needs 
to be allowed through the FORWARD chain for the above rule to work: 
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sudo iptables -A FORWARD -s 192.168.0.0/16 -o pppO -j ACCEPT 
sudo iptables -A FORWARD -d 192.168.0.0/16 -m state \ 
— State ESTABLISHED, RELATED -i pppO -j ACCEPT 

The above commands will allow all connections from your local network to the Internet and all 
traffic related to those connections to return to the machine that initiated them. 

• If you want masquerading to be enabled on reboot, which you probably do, edit /etc/rc . local 
and add any commands used above. For example add the first command with no filtering: 

iptables -t nat -A POSTROUTING -s 192.168.0.0/16 -o pppO -j MASQUERADE 

3.4. Logs 

Firewall logs are essential for recognizing attacks, troubleshooting your firewall rules, and noticing 
unusual activity on your network. You must include logging rules in your firewall for them to be 
generated, though, and logging rules must come before any applicable terminating rule (a rule with a 
target that decides the fate of the packet, such as ACCEPT, DROP, or REJECT). 

If you are using ufw, you can turn on logging by entering the following in a terminal: 
sudo ufw logging on 

To turn logging off in ufw, simply replace on with off in the above command. 
If using iptables instead of ufw, enter: 

sudo iptables -A INPUT -m state — state NEW -p tcp — dport 80 \ 
-j LOG — log-prefix "NEW_HTTP_CONN : " 

A request on port 80 from the local machine, then, would generate a log in dmesg that looks like this 
(single line split into 3 to fit this document): 

[4304885.870000] NEW_HTTP_CONN : IN=lo OUT= MAC=0 0 : 0 0 : 0 0 : 0 0 : 0 0 : 0 0 : 0 0 : 0 0 : 0 0 : 0 0 : 0 0 : 0 0 : 0 8 : 0 0 
SRC=127 . 0 . 0 . 1 DST=127 . 0 . 0 . 1 LEN=60 TOS=0x00 PREC=0x00 TTL=64 ID=58288 DF PROTO=TCP 
SPT=53981 DPT=80 WINDOW=32767 RES=0x00 SYN URGP=0 

The above log will also appear in /var/log/messages, /var/log/syslog, and /var/log/kern.log. 
This behavior can be modified by editing /etc/sysiog.conf appropriately or by installing and 
configuring ulogd and using the ULOG target instead of LOG. The ulogd daemon is a userspace 
server that listens for logging instructions from the kernel specifically for firewalls, and can log to any 
file you like, or even to a PostgreSQL or MySQL database. Making sense of your firewall logs can be 
simplified by using a log analyzing tool such as logwatch, fwanalog, fwlogwatch, or lire. 
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3.5. Other Tools 

There are many tools available to help you construct a complete firewall without intimate knowledge 
of iptables. For the GUI-inclined: 

• fwbuilder 1 is very powerful and will look familiar to an administrator who has used a commercial 
firewall utility such as Checkpoint FireWall-1. 

If you prefer a command-line tool with plain-text configuration files: 

• Shorewall 2 is a very powerful solution to help you configure an advanced firewall for any network. 

3.6. References 

• The Ubuntu Firewall 3 wiki page contains information on the development of ufw. 

• Also, the ufw manual page contains some very useful information: man ufw. 

• See the packet-filtering-HOWTO 4 for more information on using iptables. 

• The nat-HOWTO 5 contains further details on masquerading. 

• The IPTables HowTo 6 in the Ubuntu wiki is a great resource. 



http://www.fwbuilder.org/ 
http://www.shorewall.net/ 
https://wiki.ubuntu.com/UncomplicatedFirewall 

http://www.netfilter.org/documentation/HOWTO/packet-filtering-HOWTO.html 

http://www.netfilter.org/documentation/HOWTO/NAT-HOWTO.html 

https://help.ubuntu.com/community/IptablesHowTo 
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4. App Armor 

App Armor is a Linux Security Module implementation of name-based mandatory access controls. 
AppArmor confines individual programs to a set of listed files and posix 1003. le draft capabilities. 

App Armor is installed and loaded by default. It uses profiles of an application to determine what files 
and permissions the application requires. Some packages will install their own profiles, and additional 
profiles can be found in the apparmor-profiles package. 

To install the apparmor-profiles package from a terminal prompt: 

sudo apt-get install apparmor-profiles 

AppArmor profiles have two modes of execution: 

• Complaining/Learning: profile violations are permitted and logged. Useful for testing and 
developing new profiles. 

• Enforced/Confined: enforces profile policy as well as logging the violation. 

4.1 . Using AppArmor 

The apparmor-utils package contains command line utilities that you can use to change the AppArmor 
execution mode, find the status of a profile, create new profiles, etc. 

• apparmor_status is used to view the current status of AppArmor profiles. 

sudo apparmor_status 

• aa-complain places a profile into complain mode. 

sudo aa-complain /path/to/bin 

• aa-enforce places a profile into enforce mode. 

sudo aa-enforce /path/to/bin 

• The /etc/apparmor .d directory is where the AppArmor profiles are located. It can be used to 
manipulate the mode of all profiles. 

Enter the following to place all profiles into complain mode: 

sudo aa-complain /etc/apparmor .d/* 

To place all profiles in enforce mode: 

sudo aa-enforce /etc/apparmor .d/* 
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• apparmor_parser is used to load a profile into the kernel. It can also be used to reload a currently 
loaded profile using the -r option. To load a profile: 

cat /etc/apparmor .d/prof ile.name | sudo apparmorparser -a 

To reload a profile: 

cat /etc/apparmor. d/prof ile.name | sudo apparmorparser -r 

• service apparmor can be used to reload all profiles: 

sudo service apparmor reload 

• The /etc/apparmor . d/disabie directory can be used along with the apparmor_parser -R option to 
disable a profile. 

sudo In -s /etc/apparmor. d/prof ile.name /etc/apparmor . d/disable/ 
sudo apparmor_parser -R /etc/apparmor. d/prof ile.name 

To re-enable a disabled profile remove the symbolic link to the profile in /etc/apparmor . d/ 
disable/. Then load the profile using the -a option. 

sudo rm /etc/apparmor. d/disable/prof ile.name 

cat /etc/apparmor. d/prof ile.name | sudo apparmor_parser -a 

• AppArmor can be disabled, and the kernel module unloaded by entering the following: 

sudo service apparmor stop 

sudo update-rc.d -f apparmor remove 

• To re-enable AppArmor enter: 



9~ 



sudo service apparmor start 
sudo update-rc.d apparmor defaults 

Replace profile .name with the name of the profile you want to manipulate. Also, replace / 
path/to/bin/ with the actual executable file path. For example for the ping command use / 
bin/ping 

4.2. Profiles 



AppArmor profiles are simple text files located in /etc/apparmor .d/. The files are named after the 
full path to the executable they profile replacing the "/" with For example /etc/apparmor .d/ 
bin. ping is the AppArmor profile for the /bin/ping command. 

There are two main type of rules used in profiles: 

• Path entries: which detail which files an application can access in the file system. 
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• Capability entries: determine what privileges a confined process is allowed to use. 
As an example take a look at /etc/apparmor .d/bin.ping: 



#include <tunables/global> 
/bin/ping flags=( complain) { 
#include <abstractions/base> 
#include <abstractions/consoles> 
#include <abs tract ions /nameservice> 

capability net_raw, 
capability setuid, 
network inet raw, 

/bin/ping mixr, 
/etc/modules . conf r, 



Mnclude <tunablesl global> : include statements from other files. This allows statements pertaining 
to multiple applications to be placed in a common file. 

/bin/ping flags=( complain): path to the profiled program, also setting the mode to complain, 
capability net_raw,: allows the application access to the CAP_NET_RAW Posix.le capability. 
/bin/ping mixr,: allows the application read and execute access to the file. 

After editing a profile file the profile must be reloaded. See Section 4.1, "Using 



S 

App Armor" [p. 166] fox details. 



4.2.1 . Creating a Profile 

• Design a test plan: Try to think about how the application should be exercised. The test plan should 
be divided into small test cases. Each test case should have a small description and list the steps to 
follow. 

Some standard test cases are: 

• Starting the program. 

• Stopping the program. 

• Reloading the program. 

• Testing all the commands supported by the init script. 

• Generate the new profile: Use aa-genprof to generate a new profile. From a terminal: 

sudo aa-genprof executable 

For example: 

sudo aa-genprof slapd 
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• To get your new profile included in the apparmor-profiles package, file a bug in Launchpad against 
the App Armor 1 package: 

• Include your test plan and test cases. 

• Attach your new profile to the bug. 

4.2.2. Updating Profiles 

When the program is misbehaving, audit messages are sent to the log files. The program aa-logprof 
can be used to scan log files for App Armor audit messages, review them and update the profiles. 
From a terminal: 

sudo aa-logprof 

4.3. References 

• See the App Armor Administration Guide & for advanced configuration options. 

• For details using App Armor with other Ubuntu releases see the App Armor Community Wikf page. 

• The OpenSUSE AppArmor 10 page is another introduction to AppArmor. 

• A great place to ask for AppArmor assistance, and get involved with the Ubuntu Server 
community, is the #ubuntu-server IRC channel on freenode 11 . 



https://bugs.launchpad.net/ubuntu/+source/apparmor/+filebug 

o 

http://www.novell.com/documentation/apparmor/apparmor201_spl0_admin/index.html?page=/documentation/apparmor/ 

apparmor20 1 _sp 1 0_admin/data/book_apparmor_admin .html 
o 

https://help.ubuntu.com/community/AppArmor 
10 http://en.opensuse.Org/SDB:AppArmor_geeks 
http://freenode.net 
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5. Certificates 



One of the most common forms of cryptography today is public-key cryptography. Public-key 
cryptography utilizes a public key and a private key. The system works by encrypting information 
using the public key. The information can then only be decrypted using the private key. 

A common use for public-key cryptography is encrypting application traffic using a Secure Socket 
Layer (SSL) or Transport Layer Security (TLS) connection. For example, configuring Apache to 
provide HTTPS, the HTTP protocol over SSL. This allows a way to encrypt traffic using a protocol 
that does not itself provide encryption. 

A Certificate is a method used to distribute a public key and other information about a server and 
the organization who is responsible for it. Certificates can be digitally signed by a Certification 
Authority or CA. A CA is a trusted third party that has confirmed that the information contained in the 
certificate is accurate. 



5.1. Types of Certificates 



To set up a secure server using public -key cryptography, in most cases, you send your certificate 
request (including your public key), proof of your company's identity, and payment to a CA. The 
CA verifies the certificate request and your identity, and then sends back a certificate for your secure 
server. Alternatively, you can create your own self-signed certificate. 

I%— I Note, that self-signed certificates should not be used in most production environments. 



Continuing the HTTPS example, a CA-signed certificate provides two important capabilities that a 
self-signed certificate does not: 

• Browsers (usually) automatically recognize the certificate and allow a secure connection to be 
made without prompting the user. 

• When a CA issues a signed certificate, it is guaranteeing the identity of the organization that is 
providing the web pages to the browser. 

Most Web browsers, and computers, that support SSL have a list of CAs whose certificates they 
automatically accept. If a browser encounters a certificate whose authorizing CA is not in the list, the 
browser asks the user to either accept or decline the connection. Also, other applications may generate 
an error message when using a self-signed certificate. 

The process of getting a certificate from a CA is fairly easy. A quick overview is as follows: 

1. Create a private and public encryption key pair. 

2. Create a certificate request based on the public key. The certificate request contains information 
about your server and the company hosting it. 
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3. Send the certificate request, along with documents proving your identity, to a CA. We cannot tell 
you which certificate authority to choose. Your decision may be based on your past experiences, or 
on the experiences of your friends or colleagues, or purely on monetary factors. 

Once you have decided upon a CA, you need to follow the instructions they provide on how to 
obtain a certificate from them. 

4. When the CA is satisfied that you are indeed who you claim to be, they send you a digital 
certificate. 

5. Install this certificate on your secure server, and configure the appropriate applications to use the 
certificate. 

5.2. Generating a Certificate Signing Request (CSR) 

Whether you are getting a certificate from a CA or generating your own self-signed certificate, the 
first step is to generate a key. 

If the certificate will be used by service daemons, such as Apache, Postfix, Dovecot, etc, a key 
without a passphrase is often appropriate. Not having a passphrase allows the services to start without 
manual intervention, usually the preferred way to start a daemon. 

This section will cover generating a key with a passphrase, and one without. The non-passphrase key 
will then be used to generate a certificate that can be used with various service daemons. 



To generate the keys for the Certificate Signing Request (CSR) run the following command from a 
terminal prompt: 

openssl genrsa -des3 -out server. key 2048 

Generating RSA private key, 2048 bit long modulus 



e is 65537 (0x10001) 

Enter pass phrase for server. key: 

You can now enter your passphrase. For best security, it should at least contain eight characters. 
The minimum length when specifying -des3 is four characters. It should include numbers and/or 
punctuation and not be a word in a dictionary. Also remember that your passphrase is case-sensitive. 

Re-type the passphrase to verify. Once you have re-typed it correctly, the server key is generated and 
stored in the server. key file. 

Now create the insecure key, the one without a passphrase, and shuffle the key names: 



Running your secure service without a passphrase is convenient because you will not need 
to enter the passphrase every time you start your secure service. But it is insecure and a 
compromise of the key means a compromise of the server as well. 



++++++ 



++++++ 
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openssl rsa -in server. key -out server . key . insecure 
mv server. key server . key . secure 
mv server . key . insecure server. key 

The insecure key is now named server . key, and you can use this file to generate the CSR without 
passphrase. 

To create the CSR, run the following command at a terminal prompt: 
openssl req -new -key server. key -out server. csr 

It will prompt you enter the passphrase. If you enter the correct passphrase, it will prompt you to enter 
Company Name, Site Name, Email Id, etc. Once you enter all these details, your CSR will be created 
and it will be stored in the server . csr file. 

You can now submit this CSR file to a CA for processing. The CA will use this CSR file and issue the 
certificate. On the other hand, you can create self-signed certificate using this CSR. 

5.3. Creating a Self-Signed Certificate 

To create the self-signed certificate, run the following command at a terminal prompt: 

openssl x509 -req -days 365 -in server. csr -signkey server. key -out server. crt 

The above command will prompt you to enter the passphrase. Once you enter the correct passphrase, 
your certificate will be created and it will be stored in the server . crt file. 




If your secure server is to be used in a production environment, you probably need a CA- 
signed certificate. It is not recommended to use self-signed certificate. 



5.4. Installing the Certificate 

You can install the key file server .key and certificate file server, crt, or the certificate file issued 
by your CA, by running following commands at a terminal prompt: 

sudo cp server. crt /etc/ssl/certs 
sudo cp server. key /etc/ssl/private 

Now simply configure any applications, with the ability to use public -key cryptography, to use the 
certificate and key files. For example, Apache can provide HTTPS, Dovecot can provide IMAPS and 
POP3S,etc. 

5 .5 . Certification Authority 

If the services on your network require more than a few self-signed certificates it may be worth the 
additional effort to setup your own internal Certification Authority (CA). Using certificates signed 
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by your own CA, allows the various services using the certificates to easily trust other services using 
certificates issued from the same CA. 

1 . First, create the directories to hold the CA certificate and related files: 

sudo mkdir /etc/ssl/CA 

sudo mkdir /etc/ssl/newcerts 

2. The CA needs a few additional files to operate, one to keep track of the last serial number used 
by the CA, each certificate must have a unique serial number, and another file to record which 
certificates have been issued: 

sudo sh -c "echo '01' > /etc/ssl/CA/serial " 
sudo touch /etc/ssl/CA/index . txt 

3. The third file is a CA configuration file. Though not strictly necessary, it is very convenient 
when issuing multiple certificates. Edit /etc/ssi/openssi . cnf , and in the [ CA_default ] 
change: 

dir = /etc/ssl/ # Where everything is kept 

database = $dir/CA/index . txt # database index file, 

certificate = $dir/certs/cacert . pern # The CA certificate 

serial = $dir/CA/serial # The current serial number 

private_key = $dir/private/cakey . pem# The private key 

4. Next, create the self-signed root certificate: 

openssl req -new -x509 -extensions v3_ca -keyout cakey.pem -out cacert.pem -days 3650 

You will then be asked to enter the details about the certificate. 

5. Now install the root certificate and key: 

sudo mv cakey.pem /etc/ssl/private/ 
sudo mv cacert.pem /etc/ssl/certs/ 

6. You are now ready to start signing certificates. The first item needed is a Certificate Signing 
Request (CSR), see Section 5.2, "Generating a Certificate Signing Request (CSR)" [p. 171] 
for details. Once you have a CSR, enter the following to generate a certificate signed by the CA: 

sudo openssl ca -in server. csr -config /etc/ssl/openssl . cnf 

After entering the password for the CA key, you will be prompted to sign the certificate, and 
again to commit the new certificate. You should then see a somewhat large amount of output 
related to the certificate creation. 

7. There should now be a new file, /etc/ssi/newcerts/oi .pem, containing the same output. Copy 

and paste everything beginning with the line: BEGIN CERTIFICATE and continuing 

through the line: — END CERTIFICATE lines to a file named after the hostname of the 
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server where the certificate will be installed. For example mail . example . com. crt, is a nice 
descriptive name. 

Subsequent certificates will be named 02 .pem, 03 .pem, etc. 




Replace mail. example. com. crt with your own descriptive name. 



8. Finally, copy the new certificate to the host that needs it, and configure the appropriate 

applications to use it. The default location to install certificates is /etc/ssl/certs. This enables 
multiple services to use the same certificate without overly complicated file permissions. 

For applications that can be configured to use a CA certificate, you should also copy the /etc/ 
ssl/certs/cacert.pem file to the /etc/ssl/certs/ directory on each server. 

5.6. References 

• For more detailed instructions on using cryptography see the SSL Certificates HOWTO 12 by 
tlpd.org 

• The Wikipedia HTTPS 13 page has more information regarding HTTPS . 

• For more information on OpenSSL see the OpenSSL Home Page 14 . 

• Also, O'Reilly's Network Security with OpenSSL 15 is a good in depth reference. 



http://tldp.org/HOWTO/SSL-Certificates-HOWTO/index.html 

http://en.wikipedia.org/wiki/Https 

http://www.openssl.org/ 

http://oreilly.com/catalog/9780596002701/ 
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6. eCryp tfs 

eCryptfs is a POSIX-compliant enterprise-class stacked cryptographic filesystem for Linux. Layering 
on top of the filesystem layer eCryptfs protects files no matter the underlying filesystem, partition 
type, etc. 

During installation there is an option to encrypt the /home partition. This will automatically configure 
everything needed to encrypt and mount the partition. 

As an example, this section will cover configuring /srv to be encrypted using eCryptfs. 

6.1 . Using eCryp tfs 

First, install the necessary packages. From a terminal prompt enter: 

sudo apt-get install ecryptf s-utils 

Now mount the partition to be encrypted: 

sudo mount -t ecryptfs /srv /srv 

You will then be prompted for some details on how ecryptfs should encrypt the data. 

To test that files placed in /srv are indeed encrypted copy the /etc/default folder to /srv: 

sudo cp -r /etc/default /srv 

Now unmount /srv, and try to view a file: 

sudo umount /srv 

cat /srv/def ault/cron 

Remounting /srv using ecryptfs will make the data viewable once again. 

6.2. Automatically Mounting Encrypted Partitions 

There are a couple of ways to automatically mount an ecryptfs encrypted filesystem at boot. This 
example will use a /root/ . ecryptf src file containing mount options, along with a passphrase file 
residing on a USB key. 

First, create /root/ .ecryptf src containing: 

key=passphrase : passphrase_passwd_f ile=/mnt/usb/passwd_f ile . txt 
ecryptf s_sig=582 6dd62cf 81c615 
ecryptf s_cipher=aes 
ecryptf s_key_bytes= 16 
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ecryptf s_passthrough=n 

ecryptf s_enable_f ilename_crypto=n 




Adjust the ecryptfs_sig to the signature in /root/ .ecryptf s/sig-cache.txt. 



Next, create the /mnt/usb/passwd_f ile.txt passphrase file: 

passphrase_passwd= [ secrets ] 

Now add the necessary lines to /etc/f stab: 

/dev/sdbl /mnt/usb ext3 ro 0 0 

/srv /srv ecryptfs defaults 0 0 

Make sure the USB drive is mounted before the encrypted partition. 
Finally, reboot and the /srv should be mounted using eCryptfs. 

6.3. Other Utilities 

The ecryptfs-utils package includes several other useful utilities: 

• ecryptfs-setup-private : creates a -/Private directory to contain encrypted information. This utility 
can be run by unprivileged users to keep data private from other users on the system. 

• ecryptf s-mount-private and ecryptf s-umount-private: will mount and unmount respectively, a users 
-/Private directory. 

• ecryptf s-add-passphrase : adds a new passphrase to the kernel keyring. 

• ecryptf s-manager: manages eCryptfs objects such as keys. 

• ecryptf s-stat : allows you to view the ecryptfs meta information for a file. 

6.4. References 

• For more information on eCryptfs see the Launchpad project page 16 . 

• There is also a Linux Journal 17 article covering eCryptfs. 

• Also, for more ecryptfs options see the ecryptfs man page l& . 

• The eCryptfs Ubuntu Wiki 19 page also has more details. 



https://launchpad.net/ecryptfs 
http://www.linuxjournal.com/article/9400 

http://manpages.ubuntu.eom/manpages/trusty/en/man7/ecryptfs.7.html 
https://help.ubuntu.com/community/eCryptfs 
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1. Overview 

The monitoring of essential servers and services is an important part of system administration. 
Most network services are monitored for performance, availability, or both. This section will cover 
installation and configuration of Nagios for availability monitoring, and Munin for performance 
monitoring. 

The examples in this section will use two servers with hostnames serverOl and server02. ServerOl 
will be configured with Nagios to monitor services on itself and server02. ServerOl will also be setup 
with the munin package to gather information from the network. Using the munin-node package, 
server02 will be configured to send information to serverOl . 

Hopefully these simple examples will allow you to monitor additional servers and services on your 
network. 
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2. Nagios 

2.1. Installation 

First, on serverOl install the nagios package. In a terminal enter: 



sudo apt-get install nagios3 nagios-nrpe-plugin 

You will be asked to enter a password for the nagiosadmin user. The user's credentials are stored in / 
etc/nagios3/htpasswd. users. To change the nagiosadmin password, or add additional users to the 
Nagios CGI scripts, use the htpasswd that is part of the apache2-utils package. 

For example, to change the password for the nagiosadmin user enter: 

sudo htpasswd /etc/nagios3 /htpasswd. users nagiosadmin 

To add a user: 



sudo htpasswd /etc/nagios3 /htpasswd. users steve 

Next, on server02 install the nagios-nrpe-server package. From a terminal on server02 enter: 



sudo apt-get install nagios-nrpe-server 

NRPE allows you to execute local checks on remote hosts. There are other ways of 
accomplishing this through other Nagios plugins as well as other checks. 

2.2. Configuration Overview 

There are a couple of directories containing Nagios configuration and check files. 

• /etc/nagios3: contains configuration files for the operation of the nagios daemon, CGI files, hosts, 
etc. 

• /etc/nagios-plugins: houses configuration files for the service checks. 

• /etc/nagios: on the remote host contains the nagios-nrpe-server configuration files. 

• /usr/iib/nagios/plugins/: where the check binaries are stored. To see the options of a check use 
the -h option. 

For example: /usr/lib/nagios/plugins/check_dhcp -h 

There are a plethora of checks Nagios can be configured to execute for any given host. For this 
example Nagios will be configured to check disk space, DNS, and a MySQL hostgroup. The DNS 
check will be on server02, and the MySQL hostgroup will include both serverOl and server02. 
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See Section 1, "HTTPD - Apache2 Web Server" [p. 186] for details on setting up 
Apache, Chapter 8, Domain Name Service (DNS) [p. 138] for DNS, and Section 1, 
"MySQL" [p. 205] for MySQL. 



Additionally, there are some terms that once explained will hopefully make understanding Nagios 
configuration easier: 

• Host: a server, workstation, network device, etc that is being monitored. 

• Host Group: a group of similar hosts. For example, you could group all web servers, file server, etc. 

• Service: the service being monitored on the host. Such as HTTP, DNS, NFS, etc. 

• Service Group: allows you to group multiple services together. This is useful for grouping multiple 
HTTP for example. 

• Contact: person to be notified when an event takes place. Nagios can be configured to send emails, 
SMS messages, etc. 

By default Nagios is configured to check HTTP, disk space, SSH, current users, processes, and load 
on the localhost. Nagios will also ping check the gateway. 

Large Nagios installations can be quite complex to configure. It is usually best to start small, one or 
two hosts, get things configured the way you like then expand. 



2.3. Configuration 



1 . First, create a host configuration file for serverOl. Unless otherwise specified, run all these 
commands on serverOl . In a terminal enter: 



sudo cp /etc/nagios3/conf . d/localhost_nagios2 . cf g \ 
/etc /nagios 3 /conf .d/server02 . cf g 



In the above and following command examples, replace "serverOl ", "serverOl" 
172.18.100.100, and 172.18.100.101 with the host names and IP addresses of your 
servers. 



2. Next, edit /etc/nagios3/conf . d/server02 . cf g: 



define host{ 
use 

host_name 

alias 

address 

} 



generic-host ; Name of host template to use 

server02 

Server 02 

172 . 18 . 100 . 101 



# check DNS service, 
define service { 
use 

host_name 

service_description 



generxc- service 

server02 

DNS 
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check_command check_dns 1172.18.100.101 

} 

3. Restart the nagios daemon to enable the new configuration: 

sudo service nagios3 restart 

1 . Now add a service definition for the MySQL check by adding the following to /etc /nagios 3/ 
conf . d/services_nagios2 . cf g: 

# check MySQL servers . 
define service { 

hostgroup_name mysql-servers 

service_description MySQL 

check_command check_mysql_cmdlinecred ! nagios ! secret ! $HOSTADDRESS 

use generic-service 

notif ication_interval 0 ; set > 0 if you want to be renotified 

} 

2. A mysql-servers hostgroup now needs to be defined. Edit /etc/nagios3/conf . d/ 
hostgroups_nagios2 .cfg adding: 



# MySQL hostgroup. 
define hostgroup { 

hostgroup_name mysql-servers 

alias MySQL servers 

members localhost, server02 

} 

3. The Nagios check needs to authenticate to MySQL. To add a nagios user to MySQL enter: 



mysql -u root -p -e "create user nagios identified by 'secret';" 

The nagios user will need to be added all hosts in the mysql-servers hostgroup. 



4. Restart nagios to start checking the MySQL servers. 

sudo service nagios3 restart 

1 . Lastly configure NRPE to check the disk space on server 02. 

On serverOl add the service check to /etc/nagios3/conf .d/server02.cfg: 



# NRPE disk check, 
define service { 

use generic-service 

host_name server02 

service_description nrpe-disk 

check_command check_nrpe_larg ! check_all_disks 1172.18.100.101 

} 
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2. Now on server02 edit /etc/nagios/nrpe.cf g changing: 

allowed_hosts=172 . 18 . 100 . 100 

And below in the command definition area add: 

command[ check_all_disks ] =/usr/lib/nagios/plugins/check_disk -w 20% -c 10% -e 

3 . Finally , restart nagios-nrpe-server: 

sudo service nagios-nrpe-server restart 

4. Also, on serverOl restart nagios: 

sudo service nagios3 restart 

You should now be able to see the host and service checks in the Nagios CGI files. To access them 
point a browser to http://server01/nagios3. You will then be prompted for the nagiosadmin username 
and password. 

2.4. References 

This section has just scratched the surface of Nagios' features. The nagios-plugins-extra and nagios- 
snmp-plugins contain many more service checks. 

• For more information see Nagios 1 website. 

• Specifically the Online Documentation 2 site. 

• There is also a list of books 3 related to Nagios and network monitoring: 

• The Nagios Ubuntu Wih 4 page also has more details. 



http://www.nagios.org/ 
http://nagios.sourceforge.net/docs/3_0/ 
http://www.nagios.org/propaganda/books/ 
https://help.ubuntu.com/community/Nagios3 
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3. Munin 

3.1. Installation 

Before installing Munin on serverOl apache2 will need to be installed. The default configuration 
is fine for running a munin server. For more information see Section 1, "HTTPD - Apache2 Web 
Server" [p. 186]. 

First, on serverOl install munin. In a terminal enter: 

sudo apt-get install munin 

Now on serverOl install the munin-node package: 

sudo apt-get install munin-node 

3.2. Configuration 

On serverOl edit the /etc/munin/munin.conf adding the IP address for server02: 

## First our "normal" host. 
[ server02 ] 

address 172.18.100.101 

Replace server02 and 172.18.100.101 with the actual hostname and IP address for your 
server. 



Next, configure munin-node on server02. Edit /etc/munin/munin-node.conf to allow access by 
serverOl : 



allow A 172\ . 18\ . 100\ . 100$ 

Replace A 172\.18\.100\.100$ with IP address for your munin server. 



Now restart munin-node on server02 for the changes to take effect: 



sudo service munin-node restart 



Finally, in a browser go to http:l I serverOl /munin, and you should see links to nice graphs displaying 
information from the standard munin-plugins for disk, network, processes, and system. 

A-i Since this is a new install it may take some time for the graphs to display anything useful. 



183 



Monitoring 



3.3. Additional Plugins 

The munin-plugins-extra package contains performance checks additional services such as DNS , 
DHCP, Samba, etc. To install the package, from a terminal enter: 

sudo apt-get install munin-plugins-extra 

Be sure to install the package on both the server and node machines. 

3.4. References 

• See the Munin 5 website for more details. 

• Specifically the Munin Documentation 6 page includes information on additional plugins, writing 
plugins, etc. 

• Also, there is a book in German by Open Source Press: Munin Graphisches Netzwerk- und System- 
Monitoring 7 . 



http://munin.projects.linpro.no/ 
http://munin.projects.linpro.no/wiki/Documentation 

https://www.opensourcepress.de/index.php?26&backPID=178&tt_products=152 
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Chapter 11. Web Servers 

A Web server is a software responsible for accepting HTTP requests from clients, which are known 
as Web browsers, and serving them HTTP responses along with optional data contents, which usually 
are Web pages such as HTML documents and linked objects (images, etc.). 
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1. HTTPD - Apache2 Web Server 

Apache is the most commonly used Web Server on Linux systems. Web Servers are used to serve 
Web Pages requested by client computers. Clients typically request and view Web Pages using Web 
Browser applications such as Firefox, Opera, Chromium, or Mozilla. 

Users enter a Uniform Resource Locator (URL) to point to a Web server by means of its Fully 
Qualified Domain Name (FQDN) and a path to the required resource. For example, to view the home 
page of the Ubuntu Web site 1 a user will enter only the FQDN: 

www . ubuntu . com 

To view the community 2 sub-page, a user will enter the FQDN followed by a path: 
www. ubuntu . com/community 

The most common protocol used to transfer Web pages is the Hyper Text Transfer Protocol (HTTP). 
Protocols such as Hyper Text Transfer Protocol over Secure Sockets Layer (HTTPS), and File 
Transfer Protocol (FTP), a protocol for uploading and downloading files, are also supported. 

Apache Web Servers are often used in combination with the MySQL database engine, the Hyper Text 
Preprocessor (PHP) scripting language, and other popular scripting languages such as Python and 
Perl. This configuration is termed LAMP (Linux, Apache, MySQL and Perl/Python/PHP) and forms a 
powerful and robust platform for the development and deployment of Web-based applications. 

1.1. Installation 

The Apache2 web server is available in Ubuntu Linux. To install Apache2: 

• At a terminal prompt enter the following command: 

sudo apt-get install apache2 

1.2. Configuration 

Apache2 is configured by placing directives in plain text configuration files. These directives are 
separated between the following files and directories: 

• apache2 .conf: the main Apache2 configuration file. Contains settings that are global to Apache2. 

• httpd.conf: historically the main Apache2 configuration file, named after the httpd daemon. Now 
the file does not exist. In older versions of Ubuntu the file might be present, but empty, as all 
configuration options have been moved to the below referenced directories. 



http ://www .ubuntu .com 

http ://www .ubuntu .com/community 
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• conf-available: this directory contains available configuration files. All files that were previously in 
/etc/apache2/conf .d should be moved to /etc/apache2/conf-available. 

• conf-enabled: holds symlinks to the files in /etc/apache2/conf-available. When a configuration 
file is symlinked, it will be enabled the next time apache2 is restarted. 

• envvars: file where Apache2 environment variables are set. 

• mods-available: this directory contains configuration files to both load modules and configure 
them. Not all modules will have specific configuration files, however. 

• mods-enabled: holds symlinks to the files in /etc/apache2/mods-available. When a module 
configuration file is symlinked it will be enabled the next time apache2 is restarted. 

• ports. conf: houses the directives that determine which TCP ports Apache2 is listening on. 

• sites-available: this directory has configuration files for Apache2 Virtual Hosts. Virtual Hosts 
allow Apache2 to be configured for multiple sites that have separate configurations. 

• sites-enabled: like mods-enabled, sites-enabled contains symlinks to the /etc/apache2/sites- 
avaiiabie directory. Similarly when a configuration file in sites-available is symlinked, the site 
configured by it will be active once Apache2 is restarted. 

• magic: instructions for determining MIME type based on the first few bytes of a file. 

In addition, other configuration files may be added using the Include directive, and wildcards can be 
used to include many configuration files. Any directive may be placed in any of these configuration 
files. Changes to the main configuration files are only recognized by Apache2 when it is started or 
restarted. 

The server also reads a file containing mime document types; the filename is set by the TypesConfig 
directive, typically via /etc/apache2/mods-available/mime.conf , which might also include 
additions and overrides, and is /etc/mime. types by default. 

1.2.1 . Basic Settings 

This section explains Apache2 server essential configuration parameters. Refer to the Apachel 
Documentation^ for more details. 

• Apache2 ships with a virtual-host- friendly default configuration. That is, it is configured with a 
single default virtual host (using the VirtualHost directive) which can modified or used as-is if you 
have a single site, or used as a template for additional virtual hosts if you have multiple sites. If left 
alone, the default virtual host will serve as your default site, or the site users will see if the URL 
they enter does not match the ServerName directive of any of your custom sites. To modify the 
default virtual host, edit the file /etc/apache2/sites-available/000-def ault.conf . 

The directives set for a virtual host only apply to that particular virtual host. If a directive 
is set server-wide and not defined within the virtual host settings, the default setting is 



3 



http://httpd.apache .org/docs/2 .4/ 
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used. For example, you can define a Webmaster email address and not define individual 
email addresses for each virtual host. 

If you wish to configure a new virtual host or site, copy that file into the same directory with a 
name you choose. For example: 

sudo cp /etc/apache2/sites-available/000-def ault . conf /etc/apache2/sites-available/mynewsite . conf 

Edit the new file to configure the new site using some of the directives described below. 

• The Server Admin directive specifies the email address to be advertised for the server's 
administrator. The default value is webmaster® localhost. This should be changed to an email 
address that is delivered to you (if you are the server's administrator). If your website has a 
problem, Apache2 will display an error message containing this email address to report the problem 
to. Find this directive in your site's configuration file in /etc/apache2/sites-available. 

• The Listen directive specifies the port, and optionally the IP address, Apache2 should listen on. 
If the IP address is not specified, Apache2 will listen on all IP addresses assigned to the machine 
it runs on. The default value for the Listen directive is 80. Change this to 127.0.0.1:80 to cause 
Apache2 to listen only on your loopback interface so that it will not be available to the Internet, 
to (for example) 81 to change the port that it listens on, or leave it as is for normal operation. This 
directive can be found and changed in its own file, /etc/apache2/ports . conf 

• The ServerName directive is optional and specifies what FQDN your site should answer to. The 
default virtual host has no ServerName directive specified, so it will respond to all requests that 
do not match a ServerName directive in another virtual host. If you have just acquired the domain 
name ubunturocks.com and wish to host it on your Ubuntu server, the value of the ServerName 
directive in your virtual host configuration file should be ubunturocks.com. Add this directive to 
the new virtual host file you created earlier (/etc/apache2/sites-available/mynewsite.conf). 

You may also want your site to respond to www.ubunturocks.com, since many users will assume 
the www prefix is appropriate. Use the Server Alias directive for this. You may also use wildcards 
in the Server Alias directive. 

For example, the following configuration will cause your site to respond to any domain request 
ending in .ubunturocks.com. 

ServerAlias * . ubunturocks . com 

• The DocumentRoot directive specifies where Apache2 should look for the files that make up the 
site. The default value is /var/www/html, as specified in /etc/apache2/sites-available/000- 
def ault . conf. If desired, change this value in your site's virtual host file, and remember to create 
that directory if necessary ! 

Enable the new VirtualHost using the a2ensite utility and restart Apache2: 

sudo a2ensite mynewsite 
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sudo service apache2 restart 

I Be sure to replace mynewsite with a more descriptive name for the VirtualHost. One method 
is to name the file after the ServerName directive of the VirtualHost. 

Similarly, use the a2dissite utility to disable sites. This is can be useful when troubleshooting 
configuration problems with multiple VirtualHosts: 



sudo a2dissite mynewsite 
sudo service apache2 restart 

1.2.2. Default Settings 

This section explains configuration of the Apache2 server default settings. For example, if you add a 
virtual host, the settings you configure for the virtual host take precedence for that virtual host. For a 
directive not defined within the virtual host settings, the default value is used. 

• The Directorylndex is the default page served by the server when a user requests an index of a 
directory by specifying a forward slash (/) at the end of the directory name. 

For example, when a user requests the page http://www.example.com/this_directory/, he or she 
will get either the Directorylndex page if it exists, a server-generated directory list if it does not and 
the Indexes option is specified, or a Permission Denied page if neither is true. The server will try 
to find one of the files listed in the Directorylndex directive and will return the first one it finds. 
If it does not find any of these files and if Options Indexes is set for that directory, the server will 
generate and return a list, in HTML format, of the subdirectories and files in the directory. The 
default value, found in /etc/apache2/mods-available/dir .conf is "index.html index.cgi index.pl 
index.php index.xhtml index.htm". Thus, if Apache2 finds a file in a requested directory matching 
any of these names, the first will be displayed. 

• The ErrorDocument directive allows you to specify a file for Apache2 to use for specific error 
events. For example, if a user requests a resource that does not exist, a 404 error will occur. By 
default, Apache2 will simply return a HTTP 404 Return code. Read /etc/apache2/conf .d/ 
localized-error-pages for detailed instructions for using ErrorDocument, including locations of 
example files. 

• By default, the server writes the transfer log to the file /var/log/apache2/access . log. You can 
change this on a per-site basis in your virtual host configuration files with the CustomLog directive, 
or omit it to accept the default, specified in /etc/apache2/conf .d/other-vhosts-access- 

log. You may also specify the file to which errors are logged, via the Err or Log directive, whose 
default is /var/iog/apache2/error . log. These are kept separate from the transfer logs to aid 
in troubleshooting problems with your Apache2 server. You may also specify the LogLevel (the 
default value is "warn") and the LogFormat (see /etc/apache2/apache2 . conf for the default 
value). 

• Some options are specified on a per-directory basis rather than per-server. Options is one of these 
directives. A Directory stanza is enclosed in XML-like tags, like so: 
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<Directory /var /www/ html /mynewsite> 
</Directory> 

The Options directive within a Directory stanza accepts one or more of the following values 
(among others), separated by spaces: 

• ExecCGI - Allow execution of CGI scripts. CGI scripts are not executed if this option is not 
chosen. 



© 



Most files should not be executed as CGI scripts. This would be very dangerous. CGI 
scripts should kept in a directory separate from and outside your DocumentRoot, and 
only this directory should have the ExecCGI option set. This is the default, and the 
default location for CGI scripts is /usr/lib/cgi-bin. 

• Includes - Allow server-side includes. Server-side includes allow an HTML file to include other 
files. See Apache SSI documentation (Ubuntu community) 4 for more information. 

• IncludesNOEXEC - Allow server-side includes, but disable the #exec and Mnclude commands 
in CGI scripts. 

• Indexes - Display a formatted list of the directory's contents, if no Directorylndex (such as 
index .html) exists in the requested directory. 

OFor security reasons, this should usually not be set, and certainly should not be set on 
your DocumentRoot directory. Enable this option carefully on a per-directory basis 
only if you are certain you want users to see the entire contents of the directory. 

• Multiview - Support content- negotiated multi views; this option is disabled by default for 
security reasons. See the Apache2 documentation on this option . 

• SymLinksIfOwnerMatch - Only follow symbolic links if the target file or directory has the 
same owner as the link. 

1.2.3. httpd Settings 

This section explains some basic httpd daemon configuration settings. 

LockFile - The LockFile directive sets the path to the lockfile used when the server is compiled with 
either USE_FCNTL_SERIALIZED_ACCEPT or USE_FLOCK_SERIALIZED_ACCEPT. It must be 
stored on the local disk. It should be left to the default value unless the logs directory is located on an 
NFS share. If this is the case, the default value should be changed to a location on the local disk and to 
a directory that is readable only by root. 

PidFile - The PidFile directive sets the file in which the server records its process ID (pid). This file 
should only be readable by root. In most cases, it should be left to the default value. 



^ https://help.ubuntu.com/community/ServerSideIncludes 

^ http://httpd.apache.Org/docs/2.4/mod/mod_negotiation.html#multiviews 
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User - The User directive sets the userid used by the server to answer requests. This setting 
determines the server's access. Any files inaccessible to this user will also be inaccessible to your 
website's visitors. The default value for User is "www-data". 




Unless you know exactly what you are doing, do not set the User directive to root. Using 
root as the User will create large security holes for your Web server. 



Group - The Group directive is similar to the User directive. Group sets the group under which the 
server will answer requests. The default group is also "www-data". 

1.2.4. Apache2 Modules 

Apache2 is a modular server. This implies that only the most basic functionality is included in the 
core server. Extended features are available through modules which can be loaded into Apache2. By 
default, a base set of modules is included in the server at compile-time. If the server is compiled to use 
dynamically loaded modules, then modules can be compiled separately, and added at any time using 
the LoadModule directive. Otherwise, Apache2 must be recompiled to add or remove modules. 

Ubuntu compiles Apache2 to allow the dynamic loading of modules. Configuration directives may be 
conditionally included on the presence of a particular module by enclosing them in an <IfModule> 
block. 

You can install additional Apache2 modules and use them with your Web server. For example, run 
the following command from a terminal prompt to install the MySQL Authentication module: 

sudo apt-get install libapache2-mod-auth-mysql 

See the /etc/apache2/mods-avaiiabie directory, for additional modules. 
Use the a2enmod utility to enable a module: 

sudo a2enmod authmysql 
sudo service apache2 restart 

Similarly, a2dismod will disable a module: 

sudo a2dismod authmysql 
sudo service apache2 restart 

1.3. HTTPS Configuration 

The mod_ssl module adds an important feature to the Apache2 server - the ability to encrypt 
communications. Thus, when your browser is communicating using SSL, the https:// prefix is used at 
the beginning of the Uniform Resource Locator (URL) in the browser navigation bar. 

The mod_ssl module is available in apache2-common package. Execute the following command from 
a terminal prompt to enable the mod_ssl module: 
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sudo a2enmod ssl 

There is a default HTTPS configuration file in /etc/apache2/sites-available/default-ssl.conf . 
In order for Apache2 to provide HTTPS, a certificate and key file are also needed. The default 
HTTPS configuration will use a certificate and key generated by the ssl-cert package. They are good 
for testing, but the auto-generated certificate and key should be replaced by a certificate specific 
to the site or server. For information on generating a key and obtaining a certificate see Section 5, 
"Certificates" [p. 170] 

To configure Apache2 for HTTPS, enter the following: 



sudo a2ensite default-ssl 

The directories /etc/ssl/certs and /etc/ssl/private are the default locations. If you 
install the certificate and key in another directory make sure to change SSLCertificateFile 
and SSLCertificateKeyFile appropriately. 

With Apache2 now configured for HTTPS, restart the service to enable the new settings: 



sudo service apache2 restart 

«— I Depending on how you obtained your certificate you may need to enter a passphrase when 
Apache2 starts. 

You can access the secure server pages by typing https://your_hostname/url/ in your browser address 
bar. 

1.4. Sharing Write Permission 

For more than one user to be able to write to the same directory it will be necessary to grant write 
permission to a group they share in common. The following example grants shared write permission 
to /var /www/html to the group "webmasters". 



sudo chgrp -R webmasters /var/www/html 

sudo find /var/www/html -type d -exec chmod g=rwxs "{}" \; 
sudo find /var/www/html -type f -exec chmod g=rws "{}" \; 

If access must be granted to more than one group per directory, enable Access Control Lists 
(ACLs). 

1 .5 . References 

• Apache2 Documentation 6 contains in depth information on Apache2 configuration directives. Also, 
see the apache2-doc package for the official Apache2 docs. 



http://httpd.apache .org/docs/2 .4/ 
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• See the Mod SSL Documentation site for more SSL related information. 

• O'Reilly's Apache Cookbook? is a good resource for accomplishing specific Apache2 
configurations. 

• For Ubuntu specific Apache2 questions, ask in the #ubuntu- server IRC channel onfreenode.net 9 . 

• Usually integrated with PHP and MySQL the Apache MySQL PHP Ubuntu Wiki 10 page is a good 
resource. 



http://www.modssl.org/docs/ 
http://oreilly.com/catalog/978059600 1919/ 
http://freenode.net/ 

3 https://help.ubuntu.com/community/ApacheMySQLPHP 
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2. PHP5 - Scripting Language 

PHP is a general-purpose scripting language suited for Web development. The PHP script can be 
embedded into HTML. This section explains how to install and configure PHP5 in Ubuntu System 
with Apache2 and MySQL. 

This section assumes you have installed and configured Apache2 Web Server and MySQL Database 
Server. You can refer to Apache2 section and MySQL sections in this document to install and 
configure Apache2 and MySQL respectively. 

2.1. Installation 

The PHP5 is available in Ubuntu Linux. Unlike python and perl, which are installed in the base 
system, PHP must be added. 

• To install PHP5 you can enter the following command in the terminal prompt: 
sudo apt-get install php5 libapache2-mod-php5 

You can run PHP5 scripts from command line. To run PHP5 scripts from command line you 
should install php5-cli package. To install php5-cli you can enter the following command in the 
terminal prompt: 

sudo apt-get install php5-cli 

You can also execute PHP5 scripts without installing PHP5 Apache module. To accomplish this, 
you should install php5-cgi package. You can run the following command in a terminal prompt 
to install php5-cgi package: 

sudo apt-get install php5-cgi 

To use MySQL with PHP5 you should install php5-mysql package. To install php5-mysql you 
can enter the following command in the terminal prompt: 

sudo apt-get install php5-mysql 

Similarly, to use PostgreSQL with PHP5 you should install php5-pgsql package. To install php5- 
pgsql you can enter the following command in the terminal prompt: 

sudo apt-get install php5-pgsql 

2.2. Configuration 

Once you install PHP5, you can run PHP5 scripts from your web browser. If you have installed php5- 
cli package, you can run PHP5 scripts from your command prompt. 
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By default, the Apache 2 Web server is configured to run PHP5 scripts. In other words, the PHP5 
module is enabled in Apache2 Web server automatically when you install the module. Please verify 
if the files /etc/apache2/mods-enabled/php5 .conf and /etc/apache2/mods-enabled/php5 . load 
exist. If they do not exists, you can enable the module using a2enmod command. 

Once you install PHP5 related packages and enabled PHP5 Apache 2 module, you should restart 
Apache2 Web server to run PHP5 scripts. You can run the following command at a terminal prompt 
to restart your web server: 

sudo service apache2 restart 

2.3. Testing 

To verify your installation, you can run following PHP5 phpinfo script: 

<?php 

phpinfo ( ) ; 

?> 

You can save the content in a file phpinfo . php and place it under DocumentRoot directory of 
Apache2 Web server. When point your browser to http://hostname/phpinfo.php, it would display 
values of various PHP5 configuration parameters. 

2.4. References 

• For more in depth information see php.net 11 documentation. 

• There are a plethora of books on PHP. Two good books from O'Reilly are Learning PHP 5 12 and 
the PHP Cook Book 13 . 

• Also, see the Apache MySQL PHP Ubuntu Wiki 14 page for more information. 



http://www.php.net/docs.php 
http://oreilly.com/catalog/9780596005603/ 
http://oreilly.com/catalog/9781565926813/ 
https://help.ubuntu.com/community/ApacheMySQLPHP 
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3. Squid - Proxy Server 



Squid is a full-featured web proxy cache server application which provides proxy and cache services 
for Hyper Text Transport Protocol (HTTP), File Transfer Protocol (FTP), and other popular network 
protocols. Squid can implement caching and proxying of Secure Sockets Layer (SSL) requests 
and caching of Domain Name Server (DNS) lookups, and perform transparent caching. Squid also 
supports a wide variety of caching protocols, such as Internet Cache Protocol (ICP), the Hyper 
Text Caching Protocol (HTCP), the Cache Array Routing Protocol (CARP), and the Web Cache 
Coordination Protocol (WCCP). 

The Squid proxy cache server is an excellent solution to a variety of proxy and caching server 
needs, and scales from the branch office to enterprise level networks while providing extensive, 
granular access control mechanisms, and monitoring of critical parameters via the Simple Network 
Management Protocol (SNMP). When selecting a computer system for use as a dedicated Squid 
caching proxy server for many users ensure it is configured with a large amount of physical memory 
as Squid maintains an in-memory cache for increased performance. 

3.1. Installation 



At a terminal prompt, enter the following command to install the Squid server: 



sudo apt-get install squid3 

3.2. Configuration 

Squid is configured by editing the directives contained within the /etc/squid3/squid.conf 
configuration file. The following examples illustrate some of the directives which may be modified to 
affect the behavior of the Squid server. For more in-depth configuration of Squid, see the References 
section. 

Prior to editing the configuration file, you should make a copy of the original file and 
protect it from writing so you will have the original settings as a reference, and to re-use as 
necessary. Make this copy and protect it from writing using the following commands: 



sudo cp /etc/squid3 /squid. conf /etc/squid3 /squid. conf .original 
sudo chmod a-w /etc/squid3 /squid. conf .original 

• To set your Squid server to listen on TCP port 8888 instead of the default TCP port 3128, change 
the http_port directive as such: 



http_port 8888 

• Change the visible_hostname directive in order to give the Squid server a specific hostname. This 
hostname does not necessarily need to be the computer's hostname. In this example it is set to 

weezie 
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visible_hostname weezie 
• Using Squid's access control, you may configure use of Internet services proxied by Squid to be 
available only users with certain Internet Protocol (IP) addresses. For example, we will illustrate 
access by users of the 192.168.42.0/24 subnetwork only: 

Add the following to the bottom of the ACL section of your /etc/squid3/squid.conf file: 
acl f ortytwo_network src 192.168.42.0/24 

Then, add the following to the top of the http_access section of your /etc/squid3/squid.conf 



http_access allow f ortytwo_network 
• Using the excellent access control features of Squid, you may configure use of Internet services 
proxied by Squid to be available only during normal business hours. For example, we'll illustrate 
access by employees of a business which is operating between 9:00AM and 5:00PM, Monday 
through Friday, and which uses the 10.1.42.0/24 subnetwork: 

Add the following to the bottom of the ACL section of your /etc/squid3/squid.conf file: 

acl biz_network src 10.1.42.0/24 

acl biz_hours time M T W T F 9:00-17:00 

Then, add the following to the top of the http_access section of your /etc/squid3/squid.conf 



file: 



file: 



http_access allow biz_network biz_hours 




After making changes to the /etc/squid3/squid.conf file, save the file and restart the 
squid server application to effect the changes using the following command entered at a 
terminal prompt: 



sudo service squid3 restart 



3.3. References 



Squid Website 



15 



Ubuntu Wiki Squid page. 



15 



http://www .squid-cache .org/ 

https ://help .ubuntu .com/community/Squid 



16 
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4. Ruby on Rails 

Ruby on Rails is an open source web framework for developing database backed web applications. It 
is optimized for sustainable productivity of the programmer since it lets the programmer to write code 
by favouring convention over configuration. 

4.1. Installation 

Before installing Rails you should install Apache and MySQL. To install the Apache package, please 
refer to Section 1, "HTTPD - Apache2 Web Server" [p. 186]. For instructions on installing MySQL 
refer to Section 1, "MySQL" [p. 205]. 

Once you have Apache and MySQL packages installed, you are ready to install Ruby on Rails 
package. 

To install the Ruby base packages and Ruby on Rails, you can enter the following command in the 
terminal prompt: 

sudo apt-get Install rails 

4.2. Configuration 

Modify the /etc/apache2/sites-available/000-def ault.conf configuration file to setup your 
domains. 

The first thing to change is the DocumentRoot directive: 

DocumentRoot /path/ to/rails /application/public 

Next, change the <Directory " /path/to/rails/application/public "> directive: 

<Directory " /path/to/rails/application/public "> 

Options Indexes FollowSymLinks MultiViews ExecCGI 

AllowOverride All 

Order allow, deny 

allow from all 

AddHandler cgi-script .cgi 
</Directory> 

You should also enable the mod_rewrite module for Apache. To enable mod_rewrite module, please 
enter the following command in a terminal prompt: 

sudo a2enmod rewrite 

Finally you will need to change the ownership of the /path/to/rails/application/public and / 
path/to/raiis/appiication/tmp directories to the user used to run the Apache process: 
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sudo chown -R www-data: www-data /path/to/rails/application/public 
sudo chown -R www-data: www-data /path/to/rails/application/tmp 

That's it! Now you have your Server ready for your Ruby on Rails applications. 

4.3. References 

• See the Ruby on Rails 17 website for more information. 

• Also Agile Development with Rails l& is a great resource. 

• Another place for more information is the Ruby on Rails Ubuntu Wiki 19 page. 



http://rubyonrails.org/ 

http://pragprog.com/titles/rails3/agile-web-development-with-rails-third-edition 
https://help.ubuntu.com/community/RubyOnRails 
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5. Apache Tomcat 

Apache Tomcat is a web container that allows you to serve Java Servlets and JSP (Java Server Pages) 
web applications. 

Ubuntu has supported packages for both Tomcat 6 and 7. Tomcat 6 is the legacy version, and Tomcat 
7 is the current version where new features are implemented. Both are considered stable. This guide 
will focus on Tomcat 7, but most configuration details are valid for both versions. 

The Tomcat packages in Ubuntu support two different ways of running Tomcat. You can install them 
as a classic unique system-wide instance, that will be started at boot time will run as the tomcat7 (or 
tomcat6) unprivileged user. But you can also deploy private instances that will run with your own 
user rights, and that you should start and stop by yourself. This second way is particularly useful in a 
development server context where multiple users need to test on their own private Tomcat instances. 

5.1. System- wide installation 

To install the Tomcat server, you can enter the following command in the terminal prompt: 
sudo apt-get install tomcat7 

This will install a Tomcat server with just a default ROOT webapp that displays a minimal "It works" 
page by default. 

5.2. Configuration 

Tomcat configuration files can be found in /etc/tomcat7. Only a few common configuration tweaks 
will be described here, please see Tomcat 7.0 documentation 20 for more. 

5.2.1. Changing default ports 

By default Tomcat runs a HTTP connector on port 8080 and an AJP connector on port 8009. You 
might want to change those default ports to avoid conflict with another application on the system. 
This is done by changing the following lines in /etc/tomcat7 /server. xml: 

<Connector port="8080" protocol="HTTP/ 1 . 1 " 
connectionTimeout= "20000" 
redirectPort="8443" /> 

<Connector port="8009" protocol="AJP/ 1 . 3 " redirectPort=" 8443 " /> 



http://tomcat.apache.org/tomcat-7.0-doc/index.html 
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5.2.2. Changing JVM used 

By default Tomcat will run preferably with OpenJDK JVMs, then try the Sun JVMs, then try some 
other JVMs. You can force Tomcat to use a specific JVM by setting JAVA_HOME in /etc/default/ 
tomcat7: 



JAVA_HOME=/usr/lib/ jvm/ java-6-sun 
5.2.3. Declaring users and roles 

Usernames, passwords and roles (groups) can be defined centrally in a Servlet container. This is done 
in the /etc/tomcat7/tomcat-users.xml file: 



<role rolename= " admin " /> 

<user username=" tomcat" password="s3cret" roles="admin" /> 

5 .3 . Using Tomcat standard webapps 

Tomcat is shipped with webapps that you can install for documentation, administration or demo 
purposes. 

5.3.1. Tomcat documentation 

The tomcat7-docs package contains Tomcat documentation, packaged as a webapp that you can 
access by default at http://yourserver:8080/docs. You can install it by entering the following 
command in the terminal prompt: 



sudo apt-get install tomcat7-docs 

5.3.2. Tomcat administration webapps 

The tomcat7-admin package contains two webapps that can be used to administer the Tomcat server 
using a web interface. You can install them by entering the following command in the terminal 
prompt: 



sudo apt-get install tomcat7 -admin 

The first one is the manager webapp, which you can access by default at http://yourserver:8080/ 
manager/html. It is primarily used to get server status and restart webapps. 

Access to the manager application is protected by default: you need to define a user with the 
role "manager-gui" in /etc/tomcat7/tomcat-users.xml before you can access it. 

The second one is the host-manager webapp, which you can access by default at http:// 
yourserver:8080/host-manager/html. It can be used to create virtual hosts dynamically. 
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Access to the host-manager application is also protected by default: you need to define a 
user with the role "admin-gui" in /etc/tomcat7/tomcat-users . xmi before you can access 
it. 



For security reasons, the tomcat7 user cannot write to the /etc/tomcat7 directory by default. Some 
features in these admin webapps (application deployment, virtual host creation) need write access to 
that directory. If you want to use these features execute the following, to give users in the tomcat7 
group the necessary rights: 



sudo chgrp -R tomcat7 /etc/tomcat7 
sudo chmod -R g+w /etc/tomcat7 

5.3.3. Tomcat examples webapps 



The tomcat7 -examples package contains two webapps that can be used to test or demonstrate Servlets 
and JSP features, which you can access them by default at http://yourserver:8080/examples. You can 
install them by entering the following command in the terminal prompt: 



sudo apt-get install tomcat7 -examples 

5.4. Using private instances 

Tomcat is heavily used in development and testing scenarios where using a single system-wide 
instance doesn't meet the requirements of multiple users on a single system. The Tomcat packages 
in Ubuntu come with tools to help deploy your own user-oriented instances, allowing every user on 
a system to run (without root rights) separate private instances while still using the system-installed 
libraries. 



I It is possible to run the system-wide instance and the private instances in parallel, as long as 
they do not use the same TCP ports. 

5.4.1. Installing private instance support 

You can install everything necessary to run private instances by entering the following command in 
the terminal prompt: 



sudo apt-get install tomcat7-user 

5.4.2. Creating a private instance 

You can create a private instance directory by entering the following command in the terminal 
prompt: 



tomcat7 -instance-create my-instance 
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This will create a new my-instance directory with all the necessary subdirectories and scripts. You 
can for example install your common libraries in the lib/ subdirectory and deploy your webapps in 
the webapps/ subdirectory. No webapps are deployed by default. 

5.4.3. Configuring your private instance 

You will find the classic Tomcat configuration files for your private instance in the conf / 
subdirectory. You should for example certainly edit the conf /server .xmi file to change the default 
ports used by your private Tomcat instance to avoid conflict with other instances that might be 
running. 

5.4.4. Starting/stopping your private instance 

You can start your private instance by entering the following command in the terminal prompt 
(supposing your instance is located in the my-instance directory): 



my-instance/bin/ startup. sh 

You should check the logs/ subdirectory for any error. If you have a 
java.net. BindException: Address already in use<null> :8080 error, it means that the port 
you're using is already taken and that you should change it. 

You can stop your instance by entering the following command in the terminal prompt (supposing 
your instance is located in the my-instance directory): 



my-instance/bin/shutdown . sh 

5 .5 . References 

• See the Apache Tomcat 21 website for more information. 

• Tomcat: The Definitive Guide 22 is a good resource for building web applications with Tomcat. 

• For additional books see the Tomcat Books 21, list page. 



http://tomcat.apache.org/ 

http://shop.oreilly.com/product/9780596003180.do 
http://wiki.apache.org/tomcat/Tomcat/Books 
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Ubuntu provides two popular database servers. They are: 

• MySQL™ 

• PostgreSQL 



They are available in the main repository. This section explains how to install and configure these 
database servers. 
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1. MySQL 

MySQL is a fast, multi-threaded, multi-user, and robust SQL database server. It is intended for 
mission-critical, heavy-load production systems as well as for embedding into mass-deployed 
software. 

1.1. Installation 

To install MySQL, run the following command from a terminal prompt: 
sudo apt-get install mysql-server 

During the installation process you will be prompted to enter a password for the MySQL root user. 

Once the installation is complete, the MySQL server should be started automatically. You can run the 
following command from a terminal prompt to check whether the MySQL server is running: 

sudo netstat -tap | grep mysql 

When you run this command, you should see the following line or something similar: 

tcp 0 0 localhost:mysql *:* LISTEN 2556/mysqld 

If the server is not running correctly, you can type the following command to start it: 

sudo service mysql restart 

1.2. Configuration 

You can edit the /etc/mysql/my.cnf file to configure the basic settings — log file, port number, etc. 
For example, to configure MySQL to listen for connections from network hosts, change the bind- 
address directive to the server's IP address: 



bind-address = 192.168.0.5 

«— I Replace 192.168.0.5 with the appropriate address. 



After making a change to /etc/mysql/my.cnf the MySQL daemon will need to be restarted: 



sudo service mysql restart 

If you would like to change the MySQL root password, in a terminal enter: 



sudo dpkg-reconf igure mysql-server-5 . 5 
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The MySQL daemon will be stopped, and you will be prompted to enter a new password. 

1.3. Database Engines 

Whilst the default configuration of MySQL provided by the Ubuntu packages is perfectly functional 
and performs well there are things you may wish to consider before you proceed. 

MySQL is designed to allow data to be stored in different ways. These methods are referred to as 
either database or storage engines. There are two main engines that you'll be interested in: InnoDB 
and MylSAM. Storage engines are transparent to the end user. MySQL will handle things differently 
under the surface, but regardless of which storage engine is in use, you will interact with the database 
in the same way. 

Each engine has its own advantages and disadvantages. 

While it is possible, and may be advantageous to mix and match database engines on a table level, 
doing so reduces the effectiveness of the performance tuning you can do as you'll be splitting the 
resources between two engines instead of dedicating them to one. 

• MylSAM is the older of the two. It can be faster than InnoDB under certain circumstances and 
favours a read only workload. Some web applications have been tuned around MylSAM (though 
that's not to imply that they will slow under InnoDB). MylSAM also supports the FULLTEXT 
data type, which allows very fast searches of large quantities of text data. However MylSAM is 
only capable of locking an entire table for writing. This means only one process can update a table 
at a time. As any application that uses the table scales this may prove to be a hindrance. It also 
lacks journaling, which makes it harder for data to be recovered after a crash. The following link 
provides some points for consideration about using MylSAM on a production database 1 . 

• InnoDB is a more modern database engine, designed to be ACID compliant 2 which guarantees 
database transactions are processed reliably. Write locking can occur on a row level basis within 
a table. That means multiple updates can occur on a single table simultaneously. Data caching is 
also handled in memory within the database engine, allowing caching on a more efficient row level 
basis rather than file block. To meet ACID compliance all transactions are journaled independently 
of the main tables. This allows for much more reliable data recovery as data consistency can be 
checked. 

As of MySQL 5.5 InnoDB is the default engine, and is highly recommended over MylSAM unless 
you have specific need for features unique to the engine. 

1.4. Advanced configuration 

1.4.1. Creating a tuned my.cnf file 

There are a number of parameters that can be adjusted within MySQL's configuration file that 
will allow you to improve the performance of the server over time. For initial set-up you may find 



http://www.mysqlperformanceblog.com/2006/06/17/using-myisam-in-production/ 
http://en.wikipedia.org/wiki/ACID 
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Percona's my .cnf generating tool 3 useful. This tool will help generate a my.cnf file that will be much 
more optimised for your specific server capabilities and your requirements. 

Do not replace your existing my.cnf file with Percona's one if you have already loaded data into the 
database. Some of the changes that will be in the file will be incompatible as they alter how data is 
stored on the hard disk and you'll be unable to start MySQL. If you do wish to use it and you have 
existing data, you will need to carry out a mysqldump and reload: 

mysqldump — all-databases — routines -u root -p > ~/f ulldump . sql 

This will then prompt you for the root password before creating a copy of the data. It is advisable to 
make sure there are no other users or processes using the database whilst this takes place. Depending 
on how much data you've got in your database, this may take a while. You won't see anything on the 
screen during this process. 

Once the dump has been completed, shut down MySQL: 
sudo service mysql stop 

Now backup the original my.cnf file and replace with the new one: 

sudo cp /etc/mysql/my.cnf /etc/mysql/my. cnf .backup 
sudo cp /path/to/new/my. cnf /etc/mysql/my.cnf 

Then delete and re-initialise the database space and make sure ownership is correct before restarting 
MySQL: 

sudo rm -rf /var/lib/mysql/* 

sudo mysql_install_db 

sudo chown -R mysql: /var/lib/mysql 

sudo service mysql start 

Finally all that's left is to re-import your data. To give us an idea of how far the import process has got 
you may find the 'Pipe Viewer' utility, pv, useful. The following shows how to install and use pv for 
this case, but if you'd rather not use it just replace pv with cat in the following command. Ignore any 
ETA times produced by pv, they're based on the average time taken to handle each row of the file, but 
the speed of inserting can vary wildly from row to row with mysqldumps: 

sudo apt-get install pv 
pv -/fulldump. sql | mysql 

Once that is complete all is good to go! 



http://tools.percona.com/members/wizard 
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l%— I This is not necessary for all my.cnf changes. Most of the variables you may wish to change 
to improve performance are adjustable even whilst the server is running. As with anything, 
make sure to have a good backup copy of config files and data before making changes. 

1.4.2. MySQL Tuner 

MySQL Tuner is a useful tool that will connect to a running MySQL instance and offer suggestions 
for how it can be best configured for your workload. The longer the server has been running for, the 
better the advice mysqltuner can provide. In a production environment, consider waiting for at least 
24 hours before running the tool. You can get install mysqltuner from the Ubuntu repositories: 



sudo apt-get install mysqltuner 

Then once its been installed, run it: 



mysqltuner 

and wait for its final report. The top section provides general information about the database server, 
and the bottom section provides tuning suggestions to alter in your my.cnf. Most of these can be 
altered live on the server without restarting, look through the official MySQL documentation (link 
in Resources section) for the relevant variables to change in production. The following is part of an 
example report from a production database which shows there may be some benefit from increasing 
the amount of query cache: 



Recommendations 

General recommendations : 

Run OPTIMIZE TABLE to defragment tables for better performance 

Increase table_cache gradually to avoid file descriptor limits 
Variables to adjust: 

key_buf f er_size (> 1.4G) 

query_cache_size (> 32M) 

table_cache (> 64) 

innodb_buf f er_pool_size (>= 22G) 

One final comment on tuning databases: Whilst we can broadly say that certain settings are the best, 
performance can vary from application to application. For example, what works best for Wordpress 
might not be the best for Drupal, Joomla or proprietary applications. Performance is dependent on 
the types of queries, use of indexes, how efficient the database design is and so on. You may find 
it useful to spend some time searching for database tuning tips based on what applications you're 
using it for. Once you get past a certain point any adjustments you make will only result in minor 
improvements, and you'll be better off either improving the application, or looking at scaling up your 
database environment through either using more powerful hardware or by adding slave servers. 
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1.5. Resources 

• See the MySQL Home Page 4 for more information. 

• Full documentation is available in both online and offline formats from the MySQL Developers 
portaf 

• For general SQL information see Using SQL Special Edition^ by Rafe Colburn. 

• The Apache MySQL PHP Ubuntu Wiki 1 page also has useful information. 



http ://www .my sql.com/ 
http ://dev .my sql .com/doc/ 

http://www .informit.com/store/product .aspx?isbn=0768664128 
https://help.ubuntu.com/community/ApacheMySQLPHP 
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2. PostgreSQL 

PostgreSQL is an object-relational database system that has the features of traditional commercial 
database systems with enhancements to be found in next-generation DBMS systems. 

2.1. Installation 

To install PostgreSQL, run the following command in the command prompt: 
sudo apt-get install postgresql 

Once the installation is complete, you should configure the PostgreSQL server based on your needs, 
although the default configuration is viable. 

2.2. Configuration 

PostgreSQL supports multiple client authentication methods. IDENT authentication method is 
used for postgres and local users, unless otherwise configured. Please refer to the PostgreSQL 
Administrator's Guide % if you would like to configure alternatives like Kerberos. 

The following discussion assumes that you wish to enable TCP/IP connections and use the MD5 
method for client authentication. PostgreSQLconfiguration files are stored in the /etc/postgresql/ 
<version>/main directory. For example, if you install PostgreSQL 9.1, the configuration files are 
stored in the /etc/postgresql/9 . l/main directory. 




To configure ident authentication, add entries to the /etc/postgresql/9 . l/main/ 
pg_ident.conf file. There are detailed comments in the file to guide you. 



To enable other computers to connect to your PostgreSQL server, edit the file /etc/postgresql/9 . 1/ 
main/postgresql . conf 

Locate the line #listen_addr esses = localhost' and change it to: 
listen addresses = ' * ' 




To allow both IPv4 and IPv6 connections replace 'localhost' with '::' 



You may also edit all other parameters, if you know what you are doing! For details, refer to the 
configuration file or to the PostgreSQL documentation. 

Now that we can connect to our PostgreSQL server, the next step is to set a password for the postgres 
user. Run the following command at a terminal prompt to connect to the default PostgreSQL template 
database: 



http://www.postgresql.org/docs/9.1/static/admin.html 
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sudo -u postgres psql templatel 

The above command connects to PostgreSQL database templatel as user postgres. Once you connect 
to the PostgreSQL server, you will be at a SQL prompt. You can run the following SQL command at 
the psql prompt to configure the password for the user postgres. 

ALTER USER postgres with encrypted password ' your_pas sword ' ; 

After configuring the password, edit the file /etc/postgresqi/9 . i/main/pg_hba.conf to use MD5 
authentication with the postgres user: 



local all postgres md5 

Finally, you should restart the PostgreSQL service to initialize the new configuration. From a terminal 
prompt enter the following to restart PostgreSQL: 



sudo service postgresql restart 

The above configuration is not complete by any means. Please refer to the PostgreSQL 



Administrator's Guide 9 to configure more parameters. 
You can test server connections from other machines by using the PostgreSQL client. 



sudo apt-get install postgresql-client 
psql -h postgres.example.com -U postgres -W 

«— I Replace the domain name with your actual server domain name. 



2.3. Backups 

PostgreSQL databases should be backed up regularly. Refer to the PostgreSQL Administrator's 
Guide 10 for different approaches. 

2.4. Resources 

• As mentioned above the PostgreSQL Administrator's Guide 11 is an excellent resource. The guide is 
also available in the postgresql-doc-9.1 package. Execute the following in a terminal to install the 
package: 



sudo apt-get install postgresql-doc-9.1 



http://www.postgresql.0rg/docs/9.l/static/admin.html 
http://www.postgresql.0rg/docs/9.l/static/backup.html 
' http ://www .postgresql .org/docs/9 . 1 /static/admin .html 
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To view the guide enter file:///usr/share/doc/postgresql-doc-9.1/html/index.html into the address 
bar of your browser. 

• For general SQL information see Using SQL Special Edition 12 by Rafe Colburn. 

• Also, see the PostgreSQL Ubuntu Wiki" page for more information. 



12 

http://www .informit.com/store/product .aspx?isbn=0768664128 

13 

https://help.ubuntu.com/community/PostgreSQL 
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1. Overview 

LAMP installations (Linux + Apache + MySQL + PHP/Perl/Python) are a popular setup for Ubuntu 
servers. There is a plethora of Open Source applications written using the LAMP application stack. 
Some popular LAMP applications are Wiki's, Content Management Systems, and Management 
Software such as phpMy Admin. 

One advantage of LAMP is the substantial flexibility for different database, web server, and scripting 
languages. Popular substitutes for MySQL include PostgreSQL and SQLite. Python, Perl, and Ruby 
are also frequently used instead of PHP. While Nginx, Cherokee and Lighttpd can replace Apache. 

The fastest way to get started is to install LAMP using tasksel. Tasksel is a Debian/Ubuntu tool that 
installs multiple related packages as a co-ordinated "task" onto your system. To install a LAMP 
server: 

• At a terminal prompt enter the following command: 

sudo tasksel Install lamp-server 

After installing it you'll be able to install most LAMP applications in this way: 

• Download an archive containing the application source files. 

• Unpack the archive, usually in a directory accessible to a web server. 

• Depending on where the source was extracted, configure a web server to serve the files. 

• Configure the application to connect to the database. 

• Run a script, or browse to a page of the application, to install the database needed by the 
application. 

• Once the steps above, or similar steps, are completed you are ready to begin using the application. 

A disadvantage of using this approach is that the application files are not placed in the file system in 
a standard way, which can cause confusion as to where the application is installed. Another larger 
disadvantage is updating the application. When a new version is released, the same process used to 
install the application is needed to apply updates. 

Fortunately, a number of LAMP applications are already packaged for Ubuntu, and are available for 
installation in the same way as non-LAMP applications. Depending on the application some extra 
configuration and setup steps may be needed, however. 

This section covers how to install some LAMP applications. 
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2. Moin Moin 

MoinMoin is a Wiki engine implemented in Python, based on the PikiPiki Wiki engine, and licensed 
under the GNU GPL. 

2.1. Installation 



To install MoinMoin, run the following command in the command prompt: 



sudo apt-get install python-moinmoin 

You should also install apache2 web server. For installing apache2 web server, please refer 
to Section 1.1, "Installation" [p. 186] sub-section in Section 1, "HTTPD - Apache2 Web 
Server" [p. 186] section. 

2.2. Configuration 

For configuring your first Wiki application, please run the following set of commands. Let us assume 
that you are creating a Wiki named mywiki: 



cd /usr/share/moin 

sudo mkdir mywiki 

sudo cp -R data mywiki 

sudo cp -R underlay mywiki 

sudo cp server /moin. cgi mywiki 

sudo chown -R www-data .www-data mywiki 

sudo chmod -R ug+rwX mywiki 

sudo chmod -R o-rwx mywiki 

Now you should configure MoinMoin to find your new Wiki mywiki. To configure MoinMoin, open / 
etc/moin/mywiki.py file and change the following line: 

data_dir = 1 /org/mywiki/data ' 
to 

data_dir = 1 /usr/share/moin/mywiki/data ' 

Also, below the datajdir option add the data_underlay_dir. 



data_underlay_dir= 1 /usr/share/moin/mywiki/underlay ' 

«— I If the /etc/moin/mywiki.py file does not exists, you should copy /usr/share/moin/ 

conf ig/wikif arm/mywiki.py file to /etc/moin/mywiki.py file and do the above mentioned 
change. 

If you have named your Wiki as my _wiki_name you should insert a line "("my_wiki_name", 
r".*")" in /etc/moin/farmconf ig.py file after the line "("mywiki", r" .*")". 
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Once you have configured MoinMoin to find your first Wiki application mywiki, you should configure 
apache2 and make it ready for your Wiki application. 

You should add the following lines in /etc/apache2/sites-available/000-default.conf file 
inside the "<VirtualHost *>" tag: 



### moin 

ScriptAlias /mywiki " /usr/share/moin/mywiki/moin . cgi" 
alias /moin_staticl93 " /usr/share/moin/htdocs " 
<Directory /usr/share/moin/htdocs> 
Order allow, deny 
allow from all 
</Directory> 
### end moin 



Once you configure the apache2 web server and make it ready for your Wiki application, you should 
restart it. You can run the following command to restart the apache2 web server: 



sudo service apache2 restart 



2.3. Verification 



You can verify the Wiki application and see if it works by pointing your web browser to the following 
URL: 



http: //localhost/mywiki 

For more details, please refer to the MoinMoin 1 web site. 

2.4. References 

• For more information see the moinmoin Wiki 2 . 

• Also, see the Ubuntu Wiki MoinMoin 1 ' page. 



http://moinmo.in/ 
http://moinmo.in/ 

https://help.ubuntu.com/community/MoinMoin 
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3. MediaWiki 

MediaWiki is an web based Wiki software written in the PHP language. It can either use MySQL or 
PostgreSQL Database Management System. 

3.1. Installation 

Before installing MediaWiki you should also install Apache2, the PHP5 scripting language and a 
Database Management System. MySQL or PostgreSQL are the most common, choose one depending 
on your need. Please refer to those sections in this manual for installation instructions. 

To install MediaWiki, run the following command in the command prompt: 
sudo apt-get install mediawiki php5-gd 

For additional MediaWiki functionality see the mediawiki-extensions package. 

3.2. Configuration 

The Apache configuration file mediawiki . conf for MediaWiki is installed in /etc/apache2/conf . d/ 
directory. You should uncomment the following line in this file to access MediaWiki application. 

# Alias /mediawiki /var/lib/mediawiki 

After you uncomment the above line, restart Apache server and access MediaWiki using the following 
url: 

http : / /localhost /mediawiki/ conf ig/ index . php 

Please read the "Checking environment..." section in this page. You should be able to fix 
many issues by carefully reading this section. 

Once the configuration is complete, you should copy the Locaisettings .php file to /etc/mediawiki 
directory: 

sudo mv /var/lib/mediawiki/conf ig/LocalSettings .php /etc/mediawiki/ 

You may also want to edit /etc/mediawiki/LocalSettings.php in order to set the memory limit 
(disabled by default): 

ini_set( ' memory_limit ' , '64M' ); 

3.3. Extensions 

The extensions add new features and enhancements for the MediaWiki application. The extensions 
give wiki administrators and end users the ability to customize MediaWiki to their requirements. 



217 



LAMP Applications 



You can download MediaWiki extensions as an archive file or checkout from the Subversion 
repository. You should copy it to /var/iib/mediawiki/extensions directory. You should also add 
the following line at the end of file: /etc/mediawiki/LocalSettings.php. 

require_once " $IP/extensions/ExtentionName/ExtentionName . php" ; 

3.4. References 

• For more details, please refer to the MediaWiki 4 web site. 

• The MediaWiki Administrators' Tutorial Guide 5 contains a wealth of information for new 
MediaWiki administrators. 

• Also, the Ubuntu Wiki MediaWiki 6 page is a good resource. 



http ://www .mediawiki .org 

http://www.packtpub.com/Mediawiki/book 

https://help.ubuntu.com/community/MediaWiki 



218 



LAMP Applications 



4. phpMy Admin 

phpMy Admin is a LAMP application specifically written for administering MySQL servers. Written 
in PHP, and accessed through a web browser, phpMy Admin provides a graphical interface for 
database administration tasks. 



4.1. Installation 



Before installing phpMy Admin you will need access to a MySQL database either on the same host as 
that phpMy Admin is installed on, or on a host accessible over the network. For more information see 
Section 1, "MySQL" [p. 205]. From a terminal prompt enter: 



sudo apt-get install phpmyadmin 

At the prompt choose which web server to be configured for phpMy Admin. The rest of this section 
will use Apache2 for the web server. 

In a browser go to httpil I servernamelphpmyadmin, replacing servername with the server's actual 
hostname. At the login, page enter root for the username, or another MySQL user, if you have any 
setup, and enter the MySQL user's password. 

Once logged in you can reset the root password if needed, create users, create/destroy databases and 
tables, etc. 

4.2. Configuration 

The configuration files for phpMy Admin are located in /etc/phpmyadmin. The main configuration 
file is /etc/phpmyadmin/conf ig.inc.php. This file contains configuration options that apply globally 
to phpMy Admin. 

To use phpMy Admin to administer a MySQL database hosted on another server, adjust the following 
in /etc/phpmyadmin/conf ig . inc . php: 



$cf g[ ' Servers '][ $i ][ 1 host 1 ] = ' db_server ' ; 

Replace db_server with the actual remote database server name or IP address. Also, be sure 
that the phpMy Admin host has permissions to access the remote database. 

Once configured, log out of phpMy Admin and back in, and you should be accessing the new server. 

The conf ig . header . inc . php and conf ig . footer . inc . php files are used to add a HTML header and 
footer to phpMy Admin. 

Another important configuration file is /etc/phpmyadmin/apache.conf , this file is symlinked to / 
etc/apache2/conf . d/phpmyadmin . conf , and is used to configure Apache2 to serve the phpMyAdmin 
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site. The file contains directives for loading PHP, directory permissions, etc. For more information on 
configuring Apache2 see Section 1, "HTTPD - Apache2 Web Server" [p. 186]. 

4.3. References 

• The phpMyAdmin documentation comes installed with the package and can be accessed from the 
phpMy Admin Documentation link (a question mark with a box around it) under the phpMyAdmin 
logo. The official docs can also be access on the phpMyAdmin 1 site. 

• Also, Mastering phpMyAdmin is a great resource. 

• A third resource is the phpMyAdmin Ubuntu Wiki page. 



http://www.phpmyadmin.net/home_page/docs.php 

http://www.packtpub.com/phpmyadmin-3rd-edition/book 

https://help.ubuntu.com/community/phpMyAdmin 
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5. WordPress 

Wordpress is a blog tool, publishing platform and CMS implemented in PHP and licensed under the 
GNU GPLv2. 

5.1. Installation 

To install WordPress, run the following comand in the command prompt: 

sudo apt-get install wordpress 

You should also install apache2 web server and mysql server. For installing apache2 web 
server, please refer to Section 1.1, "Installation" [p. 186] sub-section in Section 1, "HTTPD - 
Apache2 Web Server" [p. 186] section. For installing mysql server, please refer to Section 1.1, 
"Installation" [p. 205] sub-section in Section 1, "MySQL" [p. 205] section. 

5.2. Configuration 

For configuring your first WordPress application, configure an apache site. Open /etc/apache2/ 
sites-available/wordpress.conf and write the following lines: 

Alias /blog /usr/share/wordpress 
<Directory /usr/share/wordpress> 

Options FollowSymLinks 

AllowOverride Limit Options Filelnfo 

Directorylndex index. php 

Order allow, deny 

Allow from all 
</Directory> 

<Directory /usr/share/wordpress/wp-content> 

Options FollowSymLinks 

Order allow, deny 

Allow from all 
</Directory> 

Enable this new WordPress site 

sudo a2ensite wordpress 

Once you configure the apache2 web server and make it ready for your WordPress application, you 
should restart it. You can run the following command to restart the apache2 web server: 

sudo service apache2 restart 

To facilitate multiple WordPress installations, the name of this configuration file is based on the 
Host header of the HTTP request. This means that you can have a configuration per VirtualHost 
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by simply matching the hostname portion of this configuration with your Apache Virtual Host, 
e.g. /etc/wordpress/config- 10.211. 55 .50.php, /etc/wordpress/config-hostaliasl.php, etc. These 
instructions assume you can access Apache via the localhost hostname (perhaps by using an 
ssh tunnel) if not, replace /etc/wordpress/config-localhost.php with /etc/wordpress/config- 
NAME_OF_YOUR_VIRTUAL_HOST .php . 

Once the configuration file is written, it is up to you to choose a convention for username and 
password to mysql for each WordPress database instance. This documentation shows only one, 
localhost, example. 

Now configure WordPress to use a mysql database. Open /etc/wordpress/conf ig-iocaihost.php 
file and write the following lines: 



<?php 

define ( ' DB_NAME ' , ' wordpress ' ) ; 

define ( 'DB_USER' , 'wordpress'); 

define ( ' DB_PASSWORD ' , ' yourpasswordhere ' ) ; 

define ( 'DB_HOST' , 'localhost'); 

define ( ' WP_CONTENT_DIR ' , ' /usr/share/wordpress/wp-content ' ) ; 
?> 

Now create this mysql database. Open a temporary file with mysql commands wordpress. sql and 
write the following lines: 



CREATE DATABASE wordpress; 

GRANT SELECT , INSERT , UPDATE , DELETE , CREATE , DROP , ALTER 

ON wordpress . * 

TO wordpress@localhost 

IDENTIFIED BY 'yourpasswordhere'; 

FLUSH PRIVILEGES; 

Execute these commands. 



cat wordpress . sql | sudo mysql — def aults-extra-f ile=/etc/mysql/debian.cnf 

Your new WordPress can now be configured by visiting http:lllocalhostlbloglwp-adminlinstall.php. 
(Or http:IINAME_OF_YOUR_VIRTUAL_HOSTIbloglwp-adminlinstall.php if your server has no GUI 
and you are completing WordPress configuration via a web browser running on another computer.) 
Fill out the Site Title, username, password, and E-mail and click Install WordPress. 

Note the generated password (if applicable) and click the login password. Your WordPress is now 
ready for use. 

5.3. References 

• WordPress.org Codex 10 

10 https://codex.wordpress.org/ 
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• Ubuntu Wiki WordPress 11 



1 1 https://help.ubuntu.com/community/WordPress 
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Chapter 14. File Servers 

If you have more than one computer on a single network. At some point you will probably need to 
share files between them. In this section we cover installing and configuring FTP, NFS, and CUPS. 
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l.FTP Server 

File Transfer Protocol (FTP) is a TCP protocol for downloading files between computers. In the 
past, it has also been used for uploading but, as that method does not use encryption, user credentials 
as well as data transferred in the clear and are easily intercepted. So if you are here looking for 
a way to upload and download files securely, see the section on OpenSSH in Chapter 6, Remote 
Administration [p. 79] instead. 

FTP works on a client/server model. The server component is called an FTP daemon. It continuously 
listens for FTP requests from remote clients. When a request is received, it manages the login and sets 
up the connection. For the duration of the session it executes any of commands sent by the FTP client. 

Access to an FTP server can be managed in two ways: 

• Anonymous 

• Authenticated 

In the Anonymous mode, remote clients can access the FTP server by using the default user account 
called "anonymous" or "ftp" and sending an email address as the password. In the Authenticated mode 
a user must have an account and a password. This latter choice is very insecure and should not be 
used except in special circumstances. If you are looking to transfer files securely see SFTP in the 
section on OpenSSH-Server. User access to the FTP server directories and files is dependent on the 
permissions defined for the account used at login. As a general rule, the FTP daemon will hide the 
root directory of the FTP server and change it to the FTP Home directory. This hides the rest of the 
file system from remote sessions. 

1.1. vsftpd - FTP Server Installation 

vsftpd is an FTP daemon available in Ubuntu. It is easy to install, set up, and maintain. To install 
vsftpd you can run the following command: 

sudo apt-get Install vsftpd 

1.2. Anonymous FTP Configuration 

By default vsftpd is not configured to allow anonymous download. If you wish to enable anonymous 
download edit /etc/vsftpd.conf by changing: 

anonymous_enable=Yes 

During installation a. ftp user is created with a home directory of /srv/f tp. This is the default FTP 
directory. 

If you wish to change this location, to /srv/f iles/ftp for example, simply create a directory in 
another location and change the ftp user's home directory: 
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sudo mkdir /srv/f iles/f tp 

sudo usermod -d /srv/f iles/f tp ftp 

After making the change restart vsftpd: 
sudo restart vsftpd 

Finally, copy any files and directories you would like to make available through anonymous FTP to / 
srv/f iles/ftp, or /srv/f tp if you wish to use the default. 

1 .3 . User Authenticated FTP Configuration 

By default vsftpd is configured to authenticate system users and allow them to download files. If you 
want users to be able to upload files, edit /etc/vsf tpd.conf : 

write_enable=YES 
Now restart vsftpd: 

sudo restart vsftpd 

Now when system users login to FTP they will start in their home directories where they can 
download, upload, create directories, etc. 

Similarly, by default, anonymous users are not allowed to upload files to FTP server. To change this 
setting, you should uncomment the following line, and restart vsftpd: 

anon_upload_enable=YES 

Enabling anonymous FTP upload can be an extreme security risk. It is best to not enable 
anonymous upload on servers accessed directly from the Internet. 

The configuration file consists of many configuration parameters. The information about each 
parameter is available in the configuration file. Alternatively, you can refer to the man page, man 5 
vsftpd.conf for details of each parameter. 

1.4. Securing FTP 

There are options in /etc/vsf tpd.conf to help make vsftpd more secure. For example users can be 
limited to their home directories by uncommenting: 

chroot_local_user=YES 

You can also limit a specific list of users to just their home directories: 
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chroot_list_enable=YES 

chroot_list_f ile=/etc/vsf tpd. chroot_list 

After uncommenting the above options, create a /etc/vsftpd.chroot_list containing a list of users 
one per line. Then restart vsftpd: 

sudo restart vsftpd 

Also, the /etc/f tpusers file is a list of users that are disallowed FTP access. The default list includes 
root, daemon, nobody, etc. To disable FTP access for additional users simply add them to the list. 

FTP can also be encrypted using FTPS. Different from SFTP, FTPS is FTP over Secure Socket Layer 
(SSL). SFTP is a FTP like session over an encrypted SSH connection. A major difference is that 
users of SFTP need to have a shell account on the system, instead of a nologin shell. Providing all 
users with a shell may not be ideal for some environments, such as a shared web host. However, it 
is possible to restrict such accounts to only SFTP and disable shell interaction. See the section on 
OpenSSH-Server for more. 

To configure FTPS, edit /etc/vsf tpd.conf and at the bottom add: 
ssl_enable=Yes 

Also, notice the certificate and key related options: 

rsa_cert_file=/etc/ssl /certs /ssl-cert-snakeoil .pem 
rsa_private_key_f ile=/etc/ssl/private/ssl-cert-snakeoil . key 

By default these options are set to the certificate and key provided by the ssl-cert package. In a 
production environment these should be replaced with a certificate and key generated for the specific 
host. For more information on certificates see Section 5, "Certificates" [p. 170]. 

Now restart vsftpd, and non-anonymous users will be forced to use FTPS: 
sudo restart vsftpd 

To allow users with a shell of /usr/sbin/noiogin access to FTP, but have no shell access, edit /etc/ 
shells adding the nologin shell: 

# /etc/shells: valid login shells 

/bin/csh 

/bin/ sh 

/usr/bin/es 

/usr/bin/ksh 

/bin/ksh 

/usr/bin/rc 
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/usr/bin/tcsh 

/bin/tcsh 

/usr/bin/esh 

/bin/dash 

/bin/bash 

/bin/rbash 

/usr /bin/ screen 

/usr/sbin/nologin 

This is necessary because, by default vsftpd uses PAM for authentication, and the /etc/pam.d/ 
vsf tpd configuration file contains: 

auth required pam_shells . so 

The shells PAM module restricts access to shells listed in the /etc/shells file. 

Most popular FTP clients can be configured to connect using FTPS . The lftp command line FTP 
client has the ability to use FTPS as well. 

1.5. References 

• See the vsftpd website 1 for more information. 

• For detailed /etc/vsf tpd . conf options see the vsftpd. conf man page 2 . 



http://vsftpd.beasts.org/vsftpd_conf.html 

http://manpages.ubuntu.eom/manpages/trasty/en/man5/vsftpd.conf.5.html 
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2. Network File System (NFS) 

NFS allows a system to share directories and files with others over a network. By using NFS, users 
and programs can access files on remote systems almost as if they were local files. 

Some of the most notable benefits that NFS can provide are: 

• Local workstations use less disk space because commonly used data can be stored on a single 
machine and still remain accessible to others over the network. 

• There is no need for users to have separate home directories on every network machine. Home 
directories could be set up on the NFS server and made available throughout the network. 

• Storage devices such as floppy disks, CDROM drives, and USB Thumb drives can be used by other 
machines on the network. This may reduce the number of removable media drives throughout the 
network. 

2.1. Installation 

At a terminal prompt enter the following command to install the NFS Server: 
sudo apt-get install nf s-kernel-server 

2.2. Configuration 

You can configure the directories to be exported by adding them to the /etc/exports file. For 
example: 

/ubuntu * ( ro , sync , no_root_squash ) 
/home * ( rw, sync , no_root_squash ) 

You can replace * with one of the hostname formats. Make the hostname declaration as specific as 
possible so unwanted systems cannot access the NFS mount. 

To start the NFS server, you can run the following command at a terminal prompt: 
sudo service nf s-kernel-server start 

2.3. NFS Client Configuration 

Use the mount command to mount a shared NFS directory from another machine, by typing a 
command line similar to the following at a terminal prompt: 

sudo mount example . hostname . com: /ubuntu /local/ubuntu 




The mount point directory /local/ubuntu must exist. There should be no files or 
subdirectories in the /local/ubuntu directory. 



229 



File Servers 



An alternate way to mount an NFS share from another machine is to add a line to the /etc/f stab file. 
The line must state the hostname of the NFS server, the directory on the server being exported, and 
the directory on the local machine where the NFS share is to be mounted. 

The general syntax for the line in /etc/f stab file is as follows: 

example. hostname. com: /ubuntu /local/ubuntu nfs rsize=8 192 , wsize=8 192 , timeo=14 , intr 

If you have trouble mounting an NFS share, make sure the nfs-common package is installed on your 
client. To install nfs-common enter the following command at the terminal prompt: 



sudo apt-get install nfs-common 

2.4. References 

Linux NFSfaq 

Ubuntu Wiki NFS Howto 4 



http://nfs.sourceforge.net/ 

https://help.ubuntu.com/community/NFSv4Howto 
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3. iSCSI Initiator 



iSCSI (Internet Small Computer System Interface) is a protocol that allows SCSI commands to be 
transmitted over a network. Typically iSCSI is implemented in a SAN (Storage Area Network) 
to allow servers to access a large store of hard drive space. The iSCSI protocol refers to clients as 
initiators and iSCSI servers as targets. 

Ubuntu Server can be configured as both an iSCSI initiator and a target. This guide provides 
commands and configuration options to setup an iSCSI initiator. It is assumed that you already have 
an iSCSI target on your local network and have the appropriate rights to connect to it. The instructions 
for setting up a target vary greatly between hardware providers, so consult your vendor documentation 
to configure your specific iSCSI target. 



To configure Ubuntu Server as an iSCSI initiator install the open-iscsi package. In a terminal enter: 
sudo apt-get install open-iscsi 

3.2. iSCSI Initiator Configuration 

Once the open-iscsi package is installed, edit /etc/iscsi/iscsid.conf changing the following: 
node. startup = automatic 

You can check which targets are available by using the iscsiadm utility. Enter the following in a 
terminal: 

sudo iscsiadm -m discovery -t st -p 192.168.0.10 

• -m: determines the mode that iscsiadm executes in. 

• -t: specifies the type of discovery. 

• -p: option indicates the target IP address. 



3.1.iSCSI Initiator Install 




Change example 192.168.0.10 to the target IP address on your network. 



If the target is available you should see output similar to the following: 



192.168.0.10:3260,1 iqn . 1992-05 . com. emc : sl7b92030000520000-2 




The iqn number and IP address above will vary depending on your hardware. 



231 



File Servers 



You should now be able to connect to the iSCSI target, and depending on your target setup you may 
have to enter user credentials. Login to the iSCSI node: 

sudo iscsiadm -m node --login 

Check to make sure that the new disk has been detected using dmesg: 
dmesg | grep sd 



322384 
322797 
322843 
322846 
322896 
322899 
323230 
323233 
325312 
325729 
325732 
325735 
2486.941805 
2486.952093 
2486.954195 
2486 . 954200 
2486.954692 
support DPO 
2486.960577 
2486 . 964862 



sd 2:0:0:0: Attached scsi generic sgl type 0 

sd 2:0:0:0: [sda] 41943040 512-byte logical blocks: (21.4 GB/20.0 GiB) 

sd 2:0:0:0: [sda] Write Protect is off 

sd 2:0:0:0: [sda] Mode Sense: 03 00 00 00 

sd 2:0:0:0: [sda] Cache data unavailable 

sd 2:0:0:0: [sda] Assuming drive cache: write through 

sd 2:0:0:0: [sda] Cache data unavailable 

sd 2:0:0:0: [sda] Assuming drive cache: write through 

sda: sdal sda2 < sda5 > 

sd 2:0:0:0: [sda] Cache data unavailable 

sd 2:0:0:0: [sda] Assuming drive cache: write through 

sd 2:0:0:0: [sda] Attached SCSI disk 

sd 4:0:0:3: Attached scsi generic sg3 type 0 

sd 4:0:0:3: [sdb] 1126400000 512-byte logical blocks: (576 GB/537 GiB) 

sd 4:0:0:3: [sdb] Write Protect is off 

sd 4:0:0:3: [sdb] Mode Sense: 8f 00 00 08 

sd 4:0:0:3: [sdb] Write cache: disabled, read cache: enabled, doesn't 
: FUA 

sdb: sdbl 

sd 4:0:0:3: [sdb] Attached SCSI disk 



In the output above sdb is the new iSCSI disk. Remember this is just an example; the output you see 
on your screen will vary. 

Next, create a partition, format the file system, and mount the new iSCSI disk. In a terminal enter: 

sudo fdisk /dev/sdb 

n 

P 

enter 
w 



The above commands are from inside the fdisk utility; see man fdisk for more detailed 
instructions. Also, the cfdisk utility is sometimes more user friendly. 



Now format the file system and mount it to /srv as an example: 



sudo mkfs.ext4 /dev/sdbl 
sudo mount /dev/sdbl /srv 
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Finally, add an entry to /etc/f stab to mount the iSCSI drive during boot: 

/dev/sdbl /srv ext4 defaults , auto ,_netdev 0 0 

It is a good idea to make sure everything is working as expected by rebooting the server. 

3.3. References 

Open-iSCSI Website 5 
Debian Open-iSCSI page 6 



http://www.open-iscsi.org/ 
http://wiki.debian.org/SAN/iSCSI/open-iscsi 
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4. CUPS - Print Server 



The primary mechanism for Ubuntu printing and print services is the Common UNIX Printing 
System (CUPS). This printing system is a freely available, portable printing layer which has become 
the new standard for printing in most Linux distributions. 

CUPS manages print jobs and queues and provides network printing using the standard Internet 
Printing Protocol (IPP), while offering support for a very large range of printers, from dot-matrix 
to laser and many in between. CUPS also supports PostScript Printer Description (PPD) and auto- 
detection of network printers, and features a simple web-based configuration and administration tool. 



4.1. Installation 



To install CUPS on your Ubuntu computer, simply use sudo with the apt-get command and give the 
packages to install as the first parameter. A complete CUPS install has many package dependencies, 
but they may all be specified on the same command line. Enter the following at a terminal prompt to 
install CUPS: 



sudo apt-get install cups 

Upon authenticating with your user password, the packages should be downloaded and installed 
without error. Upon the conclusion of installation, the CUPS server will be started automatically. 

For troubleshooting purposes, you can access CUPS server errors via the error log file at: /var/log/ 
cups/error_log. If the error log does not show enough information to troubleshoot any problems 
you encounter, the verbosity of the CUPS log can be increased by changing the LogLevel directive 
in the configuration file (discussed below) to "debug" or even "debug2", which logs everything, from 
the default of "info" . If you make this change, remember to change it back once you've solved your 
problem, to prevent the log file from becoming overly large. 

4.2. Configuration 

The Common UNIX Printing System server's behavior is configured through the directives contained 
in the file /etc/cups/cupsd.conf . The CUPS configuration file follows the same syntax as the 
primary configuration file for the Apache HTTP server, so users familiar with editing Apache's 
configuration file should feel at ease when editing the CUPS configuration file. Some examples of 
settings you may wish to change initially will be presented here. 

Prior to editing the configuration file, you should make a copy of the original file and 
protect it from writing, so you will have the original settings as a reference, and to reuse as 
necessary. 

Copy the /etc/cups/cupsd.conf file and protect it from writing with the following 
commands, issued at a terminal prompt: 
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sudo cp /etc/cups/cupsd . conf /etc/cups/cupsd . conf . original 
sudo chmod a-w /etc/cups/cupsd. conf .original 

• ServerAdmin: To configure the email address of the designated administrator of the CUPS server, 
simply edit the /etc/cups/cupsd. conf configuration file with your preferred text editor, and 

add or modify the ServerAdmin line accordingly. For example, if you are the Administrator for 
the CUPS server, and your e-mail address is 'bjoy@somebigco.com', then you would modify the 
ServerAdmin line to appear as such: 

ServerAdmin bjoy@somebigco.com 

• Listen: By default on Ubuntu, the CUPS server installation listens only on the loopback interface 
at IP address 127.0.0.1. In order to instruct the CUPS server to listen on an actual network adapter's 
IP address, you must specify either a hostname, the IP address, or optionally, an IP address/port 
pairing via the addition of a Listen directive. For example, if your CUPS server resides on a local 
network at the IP address 192.168.10.250 and you'd like to make it accessible to the other systems 
on this subnetwork, you would edit the /etc/cups/cupsd. conf and add a Listen directive, as such: 

Listen 127.0.0.1:631 # existing loopback Listen 

Listen /var/run/cups/cups . sock # existing socket Listen 

Listen 192.168.10.250:631 # Listen on the LAN interface, Port 631 (IPP) 

In the example above, you may comment out or remove the reference to the Loopback address 
(127.0.0.1) if you do not wish cupsd to listen on that interface, but would rather have it only listen 
on the Ethernet interfaces of the Local Area Network (LAN). To enable listening for all network 
interfaces for which a certain hostname is bound, including the Loopback, you could create a Listen 
entry for the hostname socrates as such: 



Listen socrates: 631 # Listen on all interfaces for the hostname 'socrates' 
or by omitting the Listen directive and using Port instead, as in: 



Port 631 # Listen on port 631 on all interfaces 

For more examples of configuration directives in the CUPS server configuration file, view the 
associated system manual page by entering the following command at a terminal prompt: 



man cupsd. conf 



Whenever you make changes to the /etc/cups/cupsd. conf configuration file, you'll need 
to restart the CUPS server by typing the following command at a terminal prompt: 



sudo service cups restart 
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4.3. Web Interface 




CUPS can be configured and monitored using a web interface, which by default is available 
at http:lllocalhost:631ladmin. The web interface can be used to perform all printer 



management tasks. 

In order to perform administrative tasks via the web interface, you must either have the root account 
enabled on your server, or authenticate as a user in the Ipadmin group. For security reasons, CUPS 
won't authenticate a user that doesn't have a password. 

To add a user to the Ipadmin group, run at the terminal prompt: 
sudo usermod -aG Ipadmin username 

Further documentation is available in the Documentation/ Help tab of the web interface. 

4.4. References 

CUPS Website 7 

Debian Open-iSCSI page & 



http://www .cups.org/ 

http://wiki.debian.org/SAN/iSCSI/open-iscsi 
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Chapter 15. Email Services 

The process of getting an email from one person to another over a network or the Internet involves 
many systems working together. Each of these systems must be correctly configured for the process to 
work. The sender uses a Mail User Agent (MUA), or email client, to send the message through one or 
more Mail Transfer Agents (MTA), the last of which will hand it off to a Mail Delivery Agent (MDA) 
for delivery to the recipient's mailbox, from which it will be retrieved by the recipient's email client, 
usually via a POP3 or IMAP server. 
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1. Postfix 

Postfix is the default Mail Transfer Agent (MTA) in Ubuntu. It attempts to be fast and easy to 
administer and secure. It is compatible with the MTA sendmail. This section explains how to install 
and configure postfix. It also explains how to set it up as an SMTP server using a secure connection 
(for sending emails securely). 

$—1 This guide does not cover setting up Postfix Virtual Domains, for information on Virtual 
Domains and other advanced configurations see Section 1.7.4, "References" [p. 244]. 

1.1. Installation 

To install postfix run the following command: 
sudo apt-get install postfix 

Simply press return when the installation process asks questions, the configuration will be done in 
greater detail in the next stage. 

1.2. Basic Configuration 

To configure postfix, run the following command: 
sudo dpkg-reconf igure postfix 

The user interface will be displayed. On each screen, select the following values: 

Internet Site 
mail .example .com 
steve 

mail.example.com, localhost.localdomain, localhost 
No 

127.0.0.0/8 [::ffff: 127 .0.0.0J/104 [::1]/128 192.168.0.0/24 
0 
+ 
all 

Replace mail.example.com with the domain for which you'll accept email, 192.168.0.0/24 
with the actual network and class range of your mail server, and steve with the appropriate 
username. 

Now is a good time to decide which mailbox format you want to use. By default Postfix will use 
mbox for the mailbox format. Rather than editing the configuration file directly, you can use the 
postconf command to configure all postfix parameters. The configuration parameters will be stored in 
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/etc/postfix/main. cf file. Later if you wish to re-configure a particular parameter, you can either 
run the command or change it manually in the file. 

To configure the mailbox format for Maildir: 

sudo postconf -e ' homemailbox = Maildir/ ' 

This will place new mail in /homdusername/Maildir so you will need to configure your 
Mail Delivery Agent (MDA) to use the same path. 

1.3. SMTP Authentication 

SMTP-AUTH allows a client to identify itself through an authentication mechanism (SASL). 
Transport Layer Security (TLS) should be used to encrypt the authentication process. Once 
authenticated the SMTP server will allow the client to relay mail. 

1 . Configure Postfix for SMTP-AUTH using SASL (Dovecot SASL): 



sudo postconf -e ' smtpd_sasl_type = dovecot' 
sudo postconf -e ' smtpd_sasl_path = private/auth ' 
sudo postconf -e ' smtpd_sasl_local_domain =' 

sudo postconf -e ' smtpd_sasl_security_options = noanonymous ' 
sudo postconf -e ' broken_sasl_auth_clients = yes' 
sudo postconf -e ' smtpd_sasl_auth_enable = yes 1 
sudo postconf -e ' smtpd_recipient_restrictions = \ 

permit_sasl_authenticated, permit_mynetworks , re ject_unauth_destination ' 
«— I The smtpd_sasl jpath configuration is a path relative to the Postfix queue directory. 



2. Next, generate or obtain a digital certificate for TLS. See Section 5, "Certificates" [p. 170] for 
details. This example also uses a Certificate Authority (CA). For information on generating a CA 
certificate see Section 5.5, "Certification Authority" [p. 172]. 

«— I MUAs connecting to your mail server via TLS will need to recognize the certificate 
used for TLS. This can either be done using a certificate from a commercial CA or 
with a self-signed certificate that users manually install/accept. For MTA to MTA 
TLS certficates are never validated without advance agreement from the affected 
organizations. For MTA to MTA TLS, unless local policy requires it, there is no 
reason not to use a self-signed certificate. Refer to Section 5.3, "Creating a Self-Signed 
Certificate" [p. 172] for more details. 

3. Once you have a certificate, configure Postfix to provide TLS encryption for both incoming and 
outgoing mail: 



sudo postconf -e ' smtp_tls_security_level = may' 
sudo postconf -e ' smtpd_tls_security_level = may' 
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sudo postconf -e ' smtp_tls_note_starttls_of f er = yes ' 

sudo postconf -e ' smtpd_tls_key_f ile = /etc/ssl/private/server . key ' 

sudo postconf -e ' smtpd_tls_cert_f ile = /etc/ssl/certs/server . crt 1 

sudo postconf -e ' smtpd_tls_loglevel = 1 1 

sudo postconf -e ' smtpd_tls_received_header = yes 1 

sudo postconf -e ' myhostname = mail.example.com' 

4. If you are using your own Certificate Authority to sign the certificate enter: 



sudo postconf -e ' smtpd_tls_CAf ile = /etc/ssl/certs/cacert .pern ' 

Again, for more details about certificates see Section 5, "Certificates" [p. 170]. 

After running all the commands, Postfix is configured for SMTP-AUTH and a self-signed 
certificate has been created for TLS encryption. 

Now, the file /etc/postfix/main. cf should look like this: 



# See /usr/share/postf ix/main . cf . dist for a commented, more complete 

# version 

smtpd_banner = $myhostname ESMTP $mail_name (Ubuntu) 
biff = no 



# appending .domain is the MUA's job. 
append_dot_mydomain = no 



# Uncomment the next line to generate "delayed mail" warnings 
#delay_warning_time = 4h 

myhostname = serverl.example.com 
alias_maps = hash : /etc/aliases 
alias_database = hash : /etc/aliases 
myorigin = /etc/mailname 

mydestination = serverl.example.com, localhost.example.com, localhost 
relayhost = 

mynetworks = 127.0.0.0/8 

mailbox_command = procmail -a "$EXTENSION" 
mailbox_size_limit = 0 
recipient_delimiter = + 
inet_interf aces = all 
smtpd_sasl_local_domain = 
smtpd_sasl_auth_enable = yes 
smtpd_sasl_security_options = noanonymous 
broken_sasl_auth_clients = yes 
smtpd_recipient_restrictions = 

permit_sasl_authenticated, permit_mynetworks , re ject _unauth_destination 

smtpd_tls_auth_only = no 

smtp_tls_security_level = may 

smtpd_tls_security_level = may 

smtp_tls_note_starttls_of f er = yes 

smtpd_tls_key_f ile = /etc/ssl/private/smtpd . key 
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smtpd_tls_cert_f ile = /etc/ssl/certs/smtpd.crt 
smtpd_tls_CAf ile = /etc/ssl/certs/cacert . pern 
smtpd_tls_loglevel = 1 
smtpd_tls_received_header = yes 
smtpd_tls_session_cache_timeout = 3600s 
tls_random_source = dev: /dev/urandom 

The postfix initial configuration is complete. Run the following command to restart the postfix 
daemon: 

sudo service postfix restart 

Postfix supports SMTP-AUTH as defined in RFC2554 1 . It is based on SASL 2 . However it is still 
necessary to set up SASL authentication before you can use SMTP-AUTH. 

1.4. Configuring SASL 

Postfix supports two SASL implementations Cyrus SASL and Dovecot SASL. To enable Dovecot 
SASL the dovecot-common package will need to be installed. From a terminal prompt enter the 
following: 

sudo apt-get install dovecot-common 

Next you will need to edit /etc/dovecot/conf . d/io -master .conf . Change the following: 
service auth { 

# auth_socket_path points to this userdb socket by default. It's typically 

# used by dovecot-Ida, doveadm, possibly imap process, etc. Its default 

# permissions make it readable only by root, but you may need to relax these 

# permissions. Users that have access to this socket are able to get a list 

# of all usernames and get results of everyone's userdb lookups. 
unix_listener auth-userdb { 

#mode = 0600 
#user = 
#group = 

} 

# Postfix smtp-auth 

unix_listener /var/spool/postf ix/private/auth { 
mode = 0660 
user = postfix 
group = postfix 

} 

In order to let Outlook clients use SMTP-AUTH, in the authentication mechanisms section of /etc/ 
dovecot/conf.d/10-auth.conf change this line: 



http://www.ietf.org/rfc/rfc2554.txt 
2 http ://www .ietf.org/rfc/rfc2222 .txt 
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auth_mechanisms = plain 
To this: 



auth_mechanisms = plain login 

Once you have Dovecot configured restart it with: 



sudo service dovecot restart 

1.5. Mail-Stack Delivery 

Another option for configuring Postfix for SMTP-AUTH is using the mail-stack-delivery package 
(previously packaged as dovecot-postfix). This package will install Dovecot and configure Postfix 
to use it for both S ASL authentication and as a Mail Delivery Agent (MDA) . The package also 
configures Dovecot for IMAP, IMAPS, POP3, and POP3S. 

You may or may not want to run IMAP, IMAPS, POP3, or POP3S on your mail server. For 
example, if you are configuring your server to be a mail gateway, spam/virus filter, etc. If 
this is the case it may be easier to use the above commands to configure Postfix for SMTP- 
AUTH. 



To install the package, from a terminal prompt enter: 



sudo apt-get install mail-stack-delivery 

You should now have a working mail server, but there are a few options that you may wish to further 
customize. For example, the package uses the certificate and key from the ssl-cert package, and in a 
production environment you should use a certificate and key generated for the host. See Section 5, 
"Certificates" [p. 1 70] for more details. 

Once you have a customized certificate and key for the host, change the following options in /etc/ 
postfix/main. cf: 



smtpd_tls_cert_f ile = /etc/ssl/certs/ssl-mail . pern 
smtpd_tls_key_f ile = /etc/ssl/private/ssl-mail . key 

Then restart Postfix: 



sudo service postfix restart 



1.6. Testing 

SMTP-AUTH configuration is complete. Now it is time to test the setup. 
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To see if SMTP-AUTH and TLS work properly, run the following command: 
telnet mail.example.com 25 

After you have established the connection to the postfix mail server, type: 
ehlo mail.example.com 

If you see the following lines among others, then everything is working perfectly. Type quit to exit. 

250-STARTTLS 
250-AUTH LOGIN PLAIN 
250-AUTH=LOGIN PLAIN 
250 8BITMIME 

1.7. Troubleshooting 

This section introduces some common ways to determine the cause if problems arise. 

1.7.1. Escaping chroot 

The Ubuntu postfix package will by default install into a chroot environment for security reasons. 
This can add greater complexity when troubleshooting problems. 

To turn off the chroot operation locate for the following line in the /etc/postfix/master . cf 
configuration file: 

smtp inet n - - - - smtpd 

and modify it as follows: 

smtp inet n - n - - smtpd 

You will then need to restart Postfix to use the new configuration. From a terminal prompt enter: 

sudo service postfix restart 

1.7.2. Smtps 

If you need smtps, edit /etc/postfix/master, cf and uncomment the following line: 

smtps inet n - - - - smtpd 

-o smtpd_tls_wrappermode=yes 
-o smtpd_sasl_auth_enable=yes 

-o smtpd_client_restrictions=permit_sasl_authenticated, re ject 
-o milter macro daemon name=ORIGINATING 
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1 .7 .3 . Log Files 

Postfix sends all log messages to /var/iog/maii . log. However error and warning messages can 
sometimes get lost in the normal log output so they are also logged to /var/iog/mail.err and /var/ 
log/mail .warn respectively. 

To see messages entered into the logs in real time you can use the tail -f command: 



tail -f /var/log/mail . err 

The amount of detail that is recorded in the logs can be increased. Below are some configuration 
options for increasing the log level for some of the areas covered above. 

• To increase TLS activity logging set the smtpd_tls_loglevel option to a value from 1 to 4. 



sudo postconf -e ' smtpd_tls_loglevel = 4 ' 

• If you are having trouble sending or receiving mail from a specific domain you can add the domain 
to the debug _peer_list parameter. 



sudo postconf -e ' debug_peer_list = problem. domain ' 

• You can increase the verbosity of any Postfix daemon process by editing the /etc/postfix/ 
master . cf and adding a -v after the entry. For example edit the smtp entry: 



smtp unix _____ smtp -v 

It is important to note that after making one of the logging changes above the Postfix 
process will need to be reloaded in order to recognize the new configuration: sudo service 
postfix reload 

To increase the amount of information logged when troubleshooting SASL issues you can set the 
following options in /etc/dovecot/conf .d/10-logging.conf 



auth_debug=yes 
auth_debug_passwords=yes 

Just like Postfix if you change a Dovecot configuration the process will need to be reloaded: 
sudo service dovecot reload. 

Some of the options above can drastically increase the amount of information sent to the log 
files. Remember to return the log level back to normal after you have corrected the problem. 
Then reload the appropriate daemon for the new configuration to take affect. 

1.7.4. References 



Administering a Postfix server can be a very complicated task. At some point you may need to turn to 
the Ubuntu community for more experienced help. 
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A great place to ask for Postfix assistance, and get involved with the Ubuntu Server community, is the 
#ubuntu-server IRC channel on freenode 3 . You can also post a message to one of the Web Forums 4 . 

For in depth Postfix information Ubuntu developers highly recommend: The Book of Postfix 5 . 

Finally, the Postfix 6 website also has great documentation on all the different configuration options 
available. 

Also, the Ubuntu Wiki Postfix 7 page has more information. 



http://freenode.net 

http://www.ubuntu.com/support/community/webforums 
http://www.postfix-book.com/ 
http://www.postfix.org/documentation.html 
https://help.ubuntu.com/community/Postfix 
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2. Exim4 



Exim4 is another Message Transfer Agent (MTA) developed at the University of Cambridge for use 
on Unix systems connected to the Internet. Exim can be installed in place of sendmail, although the 
configuration of exim is quite different to that of sendmail. 

2.1. Installation 

To install exim4, run the following command: 
sudo apt-get install exim4 

2.2. Configuration 

To configure Exim4, run the following command: 
sudo dpkg-reconf igure exim4-config 

The user interface will be displayed. The user interface lets you configure many parameters. For 
example, In Exim4 the configuration files are split among multiple files. If you wish to have them in 
one file you can configure accordingly in this user interface. 

All the parameters you configure in the user interface are stored in /etc/exim4/update-exim4 .conf 
file. If you wish to re-configure, either you re-run the configuration wizard or manually edit this file 
using your favorite editor. Once you configure, you can run the following command to generate the 
master configuration file: 

sudo update-exim4 . conf 

The master configuration file, is generated and it is stored in /var/lib/exim4/ 
conf ig . autogenerated. 



o 



At any time, you should not edit the master configuration file, /var/lib/exim4/ 

conf ig. autogenerated manually. It is updated automatically every time you run update- 

exim4.conf 



You can run the following command to start Exim4 daemon. 



sudo service exim4 start 



2.3. SMTP Authentication 



This section covers configuring Exim4 to use SMTP-AUTH with TLS and SASL. 
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The first step is to create a certificate for use with TLS . Enter the following into a terminal prompt: 

sudo /usr/share/doc/exim4-base/examples/exim-gencert 

Now Exim4 needs to be configured for TLS by editing /etc/exim4/conf . d/main/03_exim4- 
conf ig_tlsoptions add the following: 

MAIN_TLS_ENABLE = yes 

Next you need to configure Exim4 to use the saslauthd for authentication. Edit /etc/exim4/ 
conf .d/auth/30_exim4-config_exampies and uncomment the plain_saslauthd_server and 
login_saslauthd_server sections : 

plain_saslauthd_server : 
driver = plaintext 
public_name = PLAIN 

server_condition = ${if saslauthd{ { $auth2 } { $auth3} } { 1 } { 0 } } 
server_set_id = $auth2 
server_prompts = : 

. if ndef AUTH_SERVER_ALLOW_NOTLS_PASSWORDS 

server_advertise_condition = ${if eq{$tls_cipher }{}{}{*} } 
. endif 

# 

login_saslauthd_server : 
driver = plaintext 
public_name = LOGIN 

server_prompts = "Username:: : Password::" 

# don't send system passwords over unencrypted connections 
server_condition = ${if saslauthd{ { $authl } { $auth2} } { 1 } { 0 } } 
server_set_id = $authl 

. if ndef AUTH_SERVER_ALLOW_NOTLS_PASSWORDS 

server_advertise_condition = ${if eq{$tls_cipher }{}{}{*} } 
.endif 

Additionally, in order for outside mail client to be able to connect to new exim server, new user needs 
to be added into exim by using the following commands. 

sudo /usr/share/doc/exim4-base/examples/exim-adduser 

Users should protect the new exim password files with the following commands. 

sudo chown root : Debian-exim /etc/exim4/passwd 
sudo chmod 640 /etc/exim4/passwd 

Finally, update the Exim4 configuration and restart the service: 
sudo update-exim4 . conf 
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sudo service exim4 restart 

2.4. Configuring SASL 

This section provides details on configuring the saslauthd to provide authentication for Exim4. 
The first step is to install the sasl2-bin package. From a terminal prompt enter the following: 

sudo apt-get install sasl2-bin 

To configure saslauthd edit the /etc/default/saslauthd configuration file and set START=no to: 
START=yes 

Next the Debian-exim user needs to be part of the sasl group in order for Exim4 to use the saslauthd 
service: 

sudo adduser Debian-exim sasl 

Now start the saslauthd service: 

sudo service saslauthd start 

Exim4 is now configured with SMTP-AUTH using TLS and SASL authentication. 

2.5. References 

• See exim.org for more information. 

• There is also an Exim4 Book 9 available. 

• Another resource is the Exim4 Ubuntu Wiki 10 page. 



http ://www .exim .org/ 

http://www.uit.co.uk/content/exim-smtp-mail-server 
3 https://help.ubuntu.com/community/Exim4 
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3. Dovecot Server 

Dovecot is a Mail Delivery Agent, written with security primarily in mind. It supports the major 
mailbox formats: mbox or Maildir. This section explain how to set it up as an imap or pop3 server. 

3.1. Installation 



To install dovecot, run the following command in the command prompt: 



sudo apt-get install dovecot-imapd dovecot-pop3d 

3.2. Configuration 



To configure dovecot, you can edit the file /etc/dovecot/dovecot. conf. You can choose the 
protocol you use. It could be pop3, pop3s (pop3 secure), imap and imaps (imap secure). A description 
of these protocols is beyond the scope of this guide. For further information, refer to the Wikipedia 
articles on POP3 n and IMAP 12 . 

IMAPS and POP3S are more secure that the simple IMAP and POP3 because they use SSL 
encryption to connect. Once you have chosen the protocol, amend the following line in the file /etc/ 
dovecot/dovecot . conf: 



protocols = pop3 pop3s imap imaps 

Next, choose the mailbox you would like to use. Dovecot supports maildir and mbox formats. These 
are the most commonly used mailbox formats. They both have their own benefits and are discussed on 
the Dovecot web site 13 . 

Once you have chosen your mailbox type, edit the file /etc/dovecot/conf .d/io-mail.conf and 
change the following line: 

mail_location = maildir : -/Maildir # (for maildir) 
or 

mail_location = mbox : -/mail : INBOX=/var/spool/mail/%u # (for mbox) 

You should configure your Mail Transport Agent (MTA) to transfer the incoming mail to 
this type of mailbox if it is different from the one you have configured. 

Once you have configured dovecot, restart the dovecot daemon in order to test your setup: 



sudo service dovecot restart 



http://en.wikipedia.org/wiki/POP3 

http://en.wikipedia.org/wiki/Internet_Message_Access_Protocol 
http://wiki2.dovecot.org/MailboxFormat 
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If you have enabled imap, or pop3, you can also try to log in with the commands telnet localhost 
pop3 or telnet localhost imap2. If you see something like the following, the installation has been 
successful: 

bhuvan@ rainbow: ~$ telnet localhost pop3 
Trying 127 . 0.0.1... 

Connected to localhost . localdomain . 
Escape character is ' * ] ' . 
+OK Dovecot ready. 

3.3. Dovecot SSL Configuration 

To configure dovecot to use SSL, you can edit the file /etc/dovecot/conf .d/io-ssi.conf and 
amend following lines: 

ssl = yes 

ssl_cert = </etc/ssl/certs/dovecot.pem 
ssl_key = </etc/ssl/private/dovecot.pem 

You can get the SSL certificate from a Certificate Issuing Authority or you can create self signed 
SSL certificate. The latter is a good option for email, because SMTP clients rarely complain about 
"self-signed certificates". Please refer to Section 5, "Certificates" [p. 170] for details about how 
to create self signed SSL certificate. Once you create the certificate, you will have a key file and a 
certificate file. Please copy them to the location pointed in the /etc/dovecot/conf .d/io-ssl.conf 
configuration file. 

3.4. Firewall Configuration for an Email Server 

To access your mail server from another computer, you must configure your firewall to allow 
connections to the server on the necessary ports. 

• IMAP - 143 

• IMAPS-993 

• POP3 - 110 

• POP3S-995 

3.5. References 

• See the Dovecot website 14 for more information. 

• Also, the Dovecot Ubuntu Wiki 15 page has more details. 



http://www.dovecot.org/ 
https://help.ubuntu.com/community/Dovecot 
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4. Mailman 



Mailman is an open source program for managing electronic mail discussions and e-newsletter lists. 
Many open source mailing lists (including all the Ubuntu mailing lists 16 ) use Mailman as their mailing 
list software. It is powerful and easy to install and maintain. 



4.1. Installation 



Mailman provides a web interface for the administrators and users, using an external mail server to 
send and receive emails. It works perfectly with the following mail servers: 

• Postfix 

• Exim 

• Sendmail 

• Qmail 

We will see how to install and configure Mailman with, the Apache web server, and either the Postfix 
or Exim mail server. If you wish to install Mailman with a different mail server, please refer to the 
references section. 




You only need to install one mail server and Postfix is the default Ubuntu Mail Transfer 
Agent. 



4.1.1. Apache2 

To install apache2 you refer to Section 1.1, "Installation" [p. 186] for details. 

4.1.2. Postfix 



For instructions on installing and configuring Postfix refer to Section 1, "Postfix" [p. 238] 
4.1.3. Exim4 

To install Exim4 refer to Section 2, "Exim4" [p. 246]. 

Once exim4 is installed, the configuration files are stored in the /etc/exim4 directory. In Ubuntu, by 
default, the exim4 configuration files are split across different files. You can change this behavior by 
changing the following variable in the /etc/exim4/update-exim4 .conf file: 



dc_use_split_conf ig= ' true ' 
4.1.4. Mailman 

To install Mailman, run following command at a terminal prompt: 

^ http://lists.ubuntu.com 
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sudo apt-get install mailman 

It copies the installation files in /var/lib/mailman directory. It installs the CGI scripts in /usr/lib/cgi- 
bin/mailman directory. It creates list linux user. It creates the list linux group. The mailman process 
will be owned by this user. 

4.2. Configuration 

This section assumes you have successfully installed mailman, apache2, and postfix or exim4. Now 
you just need to configure them. 

4.2.1. Apache2 

An example Apache configuration file comes with Mailman and is placed in /etc/mailman/ 
apache . conf . In order for Apache to use the config file it needs to be copied to /etc/apache2/ 
sites-available: 

sudo cp /etc/mailman/apache. conf /etc/apache2 /sites-available/mailman. conf 

This will setup a new Apache VirtualHost for the Mailman administration site. Now enable the new 
configuration and restart Apache: 

sudo a2ensite mailman. conf 
sudo service apache2 restart 

Mailman uses apache2 to render its CGI scripts. The mailman CGI scripts are installed in the /usr/lib/ 
cgi43in/mailman directory. So, the mailman url will be http://hostname/cgi43in/mailman/. You can 
make changes to the /etc/apache2/sites-available/mailman.conf file if you wish to change this 
behavior. 

4.2.2. Postfix 

For Postfix integration, we will associate the domain lists.example.com with the mailing lists. Please 
replace lists.example.com with the domain of your choosing. 

You can use the postconf command to add the necessary configuration to /etc/postfix/main. cf : 

sudo postconf -e ' relay_domains = lists.example.com' 

sudo postconf -e ' transport_maps = hash: /etc/postf ix/transport ' 

sudo postconf -e ' mailman_destination_recipient_limit = 1' 

In /etc/postf ix/master.cf double check that you have the following transport: 

mailman unix - n n - - pipe 

f lags=FR user=list argv=/usr/lib/mailman/bin/postf ix-to-mailman . py 
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${nexthop} ${user} 
It calls the postfix-to-mailman. py script when a mail is delivered to a list. 

Associate the domain lists.example.com to the Mailman transport with the transport map. Edit the file 
/etc /postfix/ transport: 

lists.example.com mailman: 

Now have Postfix build the transport map by entering the following from a terminal prompt: 

sudo postmap -v /etc/postfix/transport 

Then restart Postfix to enable the new configurations: 

sudo service postfix restart 

4.2.3. Exim4 

Once Exim4 is installed, you can start the Exim server using the following command from a terminal 
prompt: 

sudo service exim4 start 

In order to make mailman work with Exim4, you need to configure Exim4. As mentioned earlier, 
by default, Exim4 uses multiple configuration files of different types. For details, please refer to 
the Exim 11 web site. To run mailman, we should add new a configuration file to the following 
configuration types: 

# Main 

# Transport 

# Router 

Exim creates a master configuration file by sorting all these mini configuration files. So, the order of 
these configuration files is very important. 

4.2.4. Main 

All the configuration files belonging to the main type are stored in the /etc/exim4/conf .d/main/ 
directory. You can add the following content to a new file, named 04_exim4-conf ig_mailman: 

# start 

# Home dir for your Mailman installation -- aka Mailman's prefix 

# directory. 

# On Ubuntu this should be " /var/lib/mailman" 



http://www.exim.org 
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# This is normally the same as -mailman 
MM_HOME=/var/ lib/mailman 

# 

# User and group for Mailman, should match your --with-mail-gid 

# switch to Mailman's configure script. Value is normally "mailman" 
MM_UID=list 

MM_GID=list 
# 

# Domains that your lists are in - colon separated list 

# you may wish to add these into local_domains as well 
domainlist mm_domains=hostname . com 

# 

# _=_=_=_=_=_=_=_=_=_=_=_=_=_=_=_=_=_=_=_=_=_=_=_=_=_=_=_=_=_= 

# 

# These values are derived from the ones above and should not need 

# editing unless you have munged your mailman installation 
# 

# The path of the Mailman mail wrapper script 
MM_WRAP=MM_HOME/mail/mailman 

# 

# The path of the list config file (used as a required file when 

# verifying list addresses) 

MM_LISTCHK=MM_HOME/lists/${lc: : $local_part} /config . pck 

# end 

4.2.5. Transport 

All the configuration files belonging to transport type are stored in the /etc/exim4/conf .d/ 
transport/ directory. You can add the following content to a new file named 4 0_exim4- 
conf ig_mailman: 

mailman_transport : 
driver = pipe 
command = MM_WRAP \ 

'${if def : local_part_suf f ix \ 

{${sg{$local_part_suffix}{-(\\w+) ( \\+ •*)?}{ \$ 1 }} } \ 
{post}}' \ 
$local_part 
current_directory = MM_HOME 
home_directory = MM_HOME 
user = MM_UID 
group = MM_GID 

4.2.6. Router 

All the configuration files belonging to router type are stored in the /etc/exim4/conf .d/router/ 
directory. You can add the following content in to a new file named ioi_exim4-conf ig_mailman: 

mailman_router : 
driver = accept 
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require_f iles = MM_HOME/lists/$local_part/conf ig.pck 
local_part_suf f ix_optional 

local_part_suf f ix = -bounces : -bounces+* : \ 

-confirm+* : -join : -leave : \ 
-owner : -request : -admin 
transport = mailman_transport 

The order of main and transport configuration files can be in any order. But, the order 
of router configuration files must be the same. This particular file must appear before 
the 200_exim4-config_primary file. These two configuration files contain same type 
of information. The first file takes the precedence. For more details, please refer to the 
references section. 

4.2.7. Mailman 



Once mailman is installed, you can run it using the following command: 



sudo service mailman start 

Once mailman is installed, you should create the default mailing list. Run the following command to 
create the mailing list: 



sudo /usr/sbin/newlist mailman 



Enter the email address of the person running the list: bhuvan at ubuntu.com 
Initial mailman password: 

To finish creating your mailing list, you must edit your /etc/aliases (or 
equivalent) file by adding the following lines, and possibly running the 
"newaliases' program: 



## mailman mailing list 
mailman : 
mailman-admin : 
mailman-bounces : 
mailman-confirm: 
mailman- join : 
mailman-leave : 
mailman-owner : 
mailman-request : 
mailman-subscribe : 
mailman-unsubscribe : 



/var/ lib/mailman /mail /mailman 
/var/ lib/mailman/mail /mailman 
/var /lib/mailman/mail /mailman 
/var /lib/mailman/mail /mailman 
/var /lib/mailman/mail /mailman 
/var /lib/mailman/mail /mailman 
/var /lib/mailman/mail /mailman 
/var /lib/mailman/mail /mailman 
/var /lib/mailman/mail /mailman 
/var /lib/mailman/mail /mailman 



post mailman" 
admin mailman" 
bounces mailman" 
confirm mailman" 
join mailman" 
leave mailman" 
owner mailman" 
request mailman" 
subscribe mailman" 
unsubscribe mailman" 



Hit enter to notify mailman owner... 



# 

We have configured either Postfix or Exim4 to recognize all emails from mailman. So, it is 
not mandatory to make any new entries in /etc/aliases. If you have made any changes to the 
configuration files, please ensure that you restart those services before continuing to next section. 
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The Exim4 does not use the above aliases to forward mails to Mailman, as it uses a discover 
approach. To suppress the aliases while creating the list, you can add MTA=None line in 
Mailman configuration file, /etc/maiiman/mm_cf g.py. 



4.3. Administration 



We assume you have a default installation. The mailman cgi scripts are still in the /usr/lib/cgi-bin/ 
mailman/ directory. Mailman provides a web based administration facility. To access this page, point 
your browser to the following url: 

http://hostname/cgi-bin/mailman/admin 

The default mailing list, mailman, will appear in this screen. If you click the mailing list name, it will 
ask for your authentication password. If you enter the correct password, you will be able to change 
administrative settings of this mailing list. You can create a new mailing list using the command line 
utility (/usr/sbin/newlist). Alternatively, you can create a new mailing list using the web interface. 

4.4. Users 



Mailman provides a web based interface for users. To access this page, point your browser to the 
following url: 

http://hostname/cgi-bin/mailman/listinfo 

The default mailing list, mailman, will appear in this screen. If you click the mailing list name, it will 
display the subscription form. You can enter your email address, name (optional), and password to 
subscribe. An email invitation will be sent to you. You can follow the instructions in the email to 
subscribe. 



4.5. References 

GNU Mailman - Installation Manual 1 * 

HOWTO - Using Exim 4 and Mailman 2.1 together 

Also, see the Mailman Ubuntu Wiki 20 page. 



http://www.list.org/mailman-install/index.html 
http://www.exim.org/howto/mailman21 .html 
https://help.ubuntu.com/community/Mailman 
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5. Mail Filtering 

One of the largest issues with email today is the problem of Unsolicited Bulk Email (UBE). Also 
known as SPAM, such messages may also carry viruses and other forms of malware. According to 
some reports these messages make up the bulk of all email traffic on the Internet. 

This section will cover integrating Amavisd-new, Spamassassin, and ClamAV with the Postfix Mail 
Transport Agent (MTA). Postfix can also check email validity by passing it through external content 
filters. These filters can sometimes determine if a message is spam without needing to process it with 
more resource intensive applications. Two common filters are opendkim and python-policyd-spf. 

• Amavisd-new is a wrapper program that can call any number of content filtering programs for spam 
detection, antivirus, etc. 

• Spamassassin uses a variety of mechanisms to filter email based on the message content. 

• ClamAV is an open source antivirus application. 

• opendkim implements a Sendmail Mail Filter (Milter) for the DomainKeys Identified Mail (DKIM) 
standard. 

• python-policyd-spf enables Sender Policy Framework (SPF) checking with Postfix. 

This is how the pieces fit together: 

• An email message is accepted by Postfix. 

• The message is passed through any external filters opendkim and python-policyd-spf in this case. 

• Amavisd-new then processes the message. 

• ClamAV is used to scan the message. If the message contains a virus Postfix will reject the 
message. 

• Clean messages will then be analyzed by Spamassassin to find out if the message is spam. 
Spamassassin will then add X-Header lines allowing Amavisd-new to further manipulate the 
message. 

For example, if a message has a Spam score of over fifty the message could be automatically dropped 
from the queue without the recipient ever having to be bothered. Another, way to handle flagged 
messages is to deliver them to the Mail User Agent (MUA) allowing the user to deal with the message 
as they see fit. 

5.1. Installation 

See Section 1, "Postfix" [p. 238] for instructions on installing and configuring Postfix. 
To install the rest of the applications enter the following from a terminal prompt: 

sudo apt-get Install amavisd-new spamassassin clamav-daemon 
sudo apt-get install opendkim postf ix-policyd-spf-python 

There are some optional packages that integrate with Spamassassin for better spam detection: 
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sudo apt-get install pyzor razor 

Along with the main filtering applications compression utilities are needed to process some email 
attachments: 

sudo apt-get Install arj cabextract cpio lha nomarch pax rar unrar unzip zip 

If some packages are not found, check that the multiverse repository is enabled in /etc /apt/ 



sources . list 



If you make changes to the file, be sure to run sudo apt-get update before trying to install 
again. 

5.2. Configuration 

Now configure everything to work together and filter email. 

5.2.1. ClamAV 

The default behaviour of ClamAV will fit our needs. For more ClamAV configuration options, check 
the configuration files in /etc/clamav. 

Add the clamav user to the amavis group in order for Amavisd-new to have the appropriate access to 
scan files: 

sudo adduser clamav amavis 
sudo adduser amavis clamav 

5.2.2. Spamassassin 

Spamassassin automatically detects optional components and will use them if they are present. This 
means that there is no need to configure pyzor and razor. 

Edit /etc/def ault/spamassassin to activate the Spamassassin daemon. Change ENABLED=0 to: 

ENABLED=1 

Now start the daemon: 

sudo service spamassassin start 

5.2.3. Amavisd-new 

First activate spam and antivirus detection in Amavisd-new by editing /etc/amavis/conf .d/15- 
content filter mode: 
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use strict; 

# You can modify this file to re-enable SPAM checking through spamassassin 

# and to re-enable antivirus checking. 

# 

# Default antivirus checking mode 

# Uncomment the two lines below to enable it 
# 

@bypass_virus_checks_maps = ( 

\%bypass_virus_checks , \@bypass_virus_checks_acl , \$bypass_virus_checks_re) ; 

# 

# Default SPAM checking mode 

# Uncomment the two lines below to enable it 
# 

@bypass_spam_checks_maps = ( 

\%bypass_spam_checks , \@bypass_spam_checks_acl, \$bypass_spam_checks_re ) ; 

1; # insure a defined return 

Bouncing spam can be a bad idea as the return address is often faked. Consider editing /etc/amavis/ 
conf . d/20-debian_def aults to set $final_spam_destiny to D_DISCARD rather than D_BOUNCE, 
as follows: 

$f inal_spam_destiny = D_DISCARD ; 

Additionally, you may want to adjust the following options to flag more messages as spam: 

$sa_tag_level_def It = -999; # add spam info headers if at, or above that level 
$sa_tag2_level_def It = 6.0; # add 'spam detected' headers at that level 
$sa_kill_level_def It = 21.0; # triggers spam evasive actions 
$sa_dsn_cutof f_level = 4; # spam level beyond which a DSN is not sent 

If the server's hostname is different from the domain's MX record you may need to manually set the 
$myhostname option. Also, if the server receives mail for multiple domains the @local_domains_acl 
option will need to be customized. Edit the /etc/amavis/conf .d/50-user file: 

$myhostname = 'mail.example.com'; 

@local_domains_acl = ( "example.com", "example.org" ); 

If you want to cover multiple domains you can use the following in the/etc/amavis/conf .d/50-user 
@local_domains_acl = qw( . ) ; 

After configuration Amavisd-new needs to be restarted: 
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sudo service amavis restart 

5.23.1.DKIMWhitelist 



Amavisd-new can be configured to automatically Whitelist addresses from domains with 
valid Domain Keys. There are some pre-configured domains in the /etc/amavis/conf .d/40- 
policy_banks. 

There are multiple ways to configure the Whitelist for a domain: 

• 'example. corn* => 'WHITELIST,: will whitelist any address from the "example.com" domain. 

• '.example .com' => 'WHITELIST';. will whitelist any address from any subdomains of 
"example.com" that have a valid signature. 

• ' .example .com/ @ example .com' => 'WHITELIST';. will whitelist subdomains of "example.com" that 
use the signature of example.com the parent domain. 

• 'J@example.com' => 'WHITELIST';. adds addresses that have a valid signature from 
"example.com". This is usually used for discussion groups that sign their messages. 

A domain can also have multiple Whitelist configurations. After editing the file, restart amavisd-new: 



sudo service amavis restart 



In this context, once a domain has been added to the Whitelist the message will not receive 
any anti-virus or spam filtering. This may or may not be the intended behavior you wish for 
a domain. 



5.2.4. Postfix 



For Postfix integration, enter the following from a terminal prompt: 



sudo postconf -e ' contentf ilter = smtp-amavis :[ 127 .0 . 0 . 1] : 10024 ' 

Next edit /etc/postfix/master . cf and add the following to the end of the file: 



smtp-amavis unix 2 smtp 

-o smtp_data_done_timeout=12 00 
-o smtp_send_xf orward_command=yes 
-o disable_dns_lookups=yes 
-o max use=20 



127.0.0.1:10025 inet n - - - - smtpd 

-o content_f ilter= 

-o local_recipient_maps= 

-o relay_recipient_maps= 

-o smtpd_restriction_classes= 

-o smtpd_delay_re ject=no 

-o smtpd_client_restrictions=permit_mynetworks , reject 
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-o smtpd_helo_restrictions= 

-o smtpd_sender_restrictions= 

-o smtpd_recipient_restrictions=permit_mynetworks , reject 

-o smtpd_data_restrictions=re ject_unauth_pipelining 

-o smtpd_end_of _data_restrictions= 

-o mynetworks=127 . 0 . 0 . 0/8 

-o smtpd_error_sleep_time=0 

-o smtpd_sof t_error_limit=1001 

-o smtpd_hard_error_limit=1000 

-o smtpd_client_connection_count_limit=0 

-o smtpd_client_connection_rate_limit=0 

-o receive_override_options=no_header_body_checks , no_unknown_recipient_checks , no_milters 
Also add the following two lines immediately below the "pickup" transport service: 

-o content_f ilter= 

-o receive_override_options=no_header_body_checks 
This will prevent messages that are generated to report on spam from being classified as spam. 
Now restart Postfix: 

sudo service postfix restart 

Content filtering with spam and virus detection is now enabled. 
5.2.5. Amavisd-new and Spamassassin 

When integrating Amavisd-new with Spamassassin, if you choose to disable the bayes filtering by 
editing /etc/spamassassin/iocal . cf and use cron to update the nightly rules, the result can cause a 
situation where a large amount of error messages are sent to the amavis user via the amavisd-new cron 
job. 

There are several ways to handle this situation: 

• Configure your MDA to filter messages you do not wish to see. 

• Change /usr/sbin/amavisd-new-cronjob to check for usejbayes 0. For example, edit /usr/sbin/ 
amavisd-new-cronjob and add the following to the top before the test statements: 

egrep -q \t ] *use_bayes [ \t]*0" /etc/spamassassin/local . cf && exit 0 

5.3. Testin g 

First, test that the Amavisd-new SMTP is listening: 

telnet localhost 10024 
Trying 127 . 0.0.1... 
Connected to localhost. 
Escape character is ' * ] ' . 
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220 [127.0.0.1] ESMTP amavisd-new service ready 
*] 

In the Header of messages that go through the content filter you should see: 
X-Spam-Level : 

X-Virus-Scanned : Debian amavisd-new at example.com 

X-Spam-Status : No, hits=-2.3 tagged_above=-1000 . 0 required=5 . 0 tests=AWL, BAYES_00 
X-Spam-Level : 



Your output will vary, but the important thing is that there are X-Virus-Scanned and X- 
Spam-Status entries. 

5.4. Troubleshooting 



The best way to figure out why something is going wrong is to check the log files. 

• For instructions on Postfix logging see the Section 1.7, "Troubleshooting" [p. 243] section. 

• Amavisd-new uses Syslog to send messages to /var/log/maii . log. The amount of detail can be 
increased by adding the $log_level option to /etc/amavis/conf .d/50-user, and setting the value 
from 1 to 5 . 

$log_level = 2; 

«— . When the Amavisd-new log output is increased Spamassassin log output is also increased. 



The ClamAV log level can be increased by editing /etc/ciamav/ciamd.conf and setting the 
following option: 

LogVerbose true 

By default ClamAV will send log messages to /var/log/clamav/clamav.log. 

After changing an applications log settings remember to restart the service for the new 
settings to take affect. Also, once the issue you are troubleshooting is resolved it is a good 
idea to change the log settings back to normal. 

5 .5 . References 



For more information on filtering mail see the following links: 

• Amavisd-new Documentation 21 

• ClamAV Documentation 22 and ClamAV Wiki 23 

21 

http://www.ijs .si/software/amavisd/amavisd-new-docs .html 

22 

http://www.clamav.net/doc/latest/html/ 

2S 

~ http://wiki.clamav.net/Main/WebHome 
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• Spamassassin Wiki 24 

• Pyzor Homepage 25 

• Razor Homepage 26 

• DKIM.org 21 

• Postfix Amavis New 2& 



Also, feel free to ask questions in the #ubuntu-server IRC channel on freenode 



29 



http://wiki.apache.org/spamassassin/ 
http://sourceforge.net/apps/trac/pyzor/ 
http://razor.sourceforge.net/ 
http://dkim.org/ 

https://help.ubuntu.com/community/PostfixAmavisNew 
http://freenode.net 
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1. Overview 

In this section, we will discuss how to install and configure a IRC server, ircd-irc2. We will also 
discuss how to install and configure Jabber, an instance messaging server. 
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2. IRC Server 

The Ubuntu repository has many Internet Relay Chat servers. This section explains how to install and 
configure the original IRC server ircd-irc2. 

2.1. Installation 

To install ircd-irc2, run the following command in the command prompt: 
sudo apt-get install ircd-irc2 

The configuration files are stored in /etc/ircd directory. The documents are available in /usr/ 
share/doc/ircd-irc2 directory. 

2.2. Configuration 

The IRC settings can be done in the configuration file /etc/ircd/ircd.conf . You can set the IRC 
host name in this file by editing the following line: 

M: ire . localhost : :Debian ircd default configuration :: 000A 

Please make sure you add DNS aliases for the IRC host name. For instance, if you set 
irc.livecipher.com as IRC host name, please make sure irc.livecipher.com is resolvable in your 
Domain Name Server. The IRC host name should not be same as the host name. 

The IRC admin details can be configured by editing the following line: 

A: Organization, IRC dept.:Daemon <ircd@example . ire . org> : Client Server :: IRCnet : 

You should add specific lines to configure the list of IRC ports to listen on, to configure Operator 
credentials, to configure client authentication, etc. For details, please refer to the example 
configuration file /usr / share/doc /ircd-irc2/ ircd. conf .example. gz. 

The IRC banner to be displayed in the IRC client, when the user connects to the server can be set in / 
etc/ircd/ircd.motd file. 

After making necessary changes to the configuration file, you can restart the IRC server using 
following command: 

sudo service ircd-irc2 restart 

2.3. References 

You may also be interested to take a look at other IRC servers available in Ubuntu Repository. It 
includes, ircd-ircu and ircd-hybrid. 
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• Refer to IRCD FAQ 1 for more details about the IRC Server. 



http://www.irc.org/tech_docs/ircnet/faq.html 
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3. Jabber Instant Messaging Server 

Jabber a popular instant message protocol is based on XMPP, an open standard for instant messaging, 
and used by many popular applications. This section covers setting up a Jabberd 2 server on a local 
LAN. This configuration can also be adapted to providing messaging services to users over the 
Internet. 

3.1. Installation 

To install jabberd2, in a terminal enter: 



sudo apt-get install jabberd2 

3.2. Configuration 

A couple of XML configuration files will be used to configure jabberd2 for Berkeley DB user 
authentication. This is a very simple form of authentication. However, jabberd2 can be configured to 
use LDAP, MySQL, PostgreSQL, etc for for user authentication. 

First, edit /etc/ jabber d2/sm.xml changing: 



<id> jabber . example . com</id> 
1 Replace jabber.example.com with the hostname, or other id, of your server. 



Now in the <storage> section change the <driver> to: 



<driver>db</driver> 
Next, edit /etc/ jabberd2/c2s.xml in the <local> section change: 



<id> jabber . example . com</id> 
And in the <authreg> section adjust the <module> section to: 



<module>db</module> 
Finally, restart jabberd2 to enable the new settings: 

sudo service jabberd2 restart 

You should now be able to connect to the server using a Jabber client like Pidgin for example. 
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The advantage of using Berkeley DB for user data is that after being configured no 
additional maintenance is required. If you need more control over user accounts and 
credentials another authentication method is recommended. 

3 .3 . References 

• The Jabberdl Web Site 2 contains more details on configuring Jabberd2. 

• For more authentication options see the Jabberdl Install Guide 3 . 

• Also, the Setting Up Jabber Server Ubuntu Wiki page has more information. 



http://codex.xiaoka.eom/wiki/jabberd2:start 
http://www.jabberdoc.org/ 

https://help.ubuntu.com/commLinity/SettingUpJabberServer 
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Version control is the art of managing changes to information. It has long been a critical tool for 
programmers, who typically spend their time making small changes to software and then undoing 
those changes the next day. But the usefulness of version control software extends far beyond the 
bounds of the software development world. Anywhere you can find people using computers to 
manage information that changes often, there is room for version control. 
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1. Bazaar 

Bazaar is a new version control system sponsored by Canonical, the commercial company behind 
Ubuntu. Unlike Subversion and CVS that only support a central repository model, Bazaar also 
supports distributed version control, giving people the ability to collaborate more efficiently. In 
particular, Bazaar is designed to maximize the level of community participation in open source 
projects. 

1.1. Installation 

At a terminal prompt, enter the following command to install bzr: 
sudo apt-get install bzr 

1.2. Configuration 

To introduce yourself to bzr, use the whoami command like this: 
$ bzr whoami 'Joe Doe <joe . doe@gmail . com> ' 

1.3. Learning Bazaar 

Bazaar comes with bundled documentation installed into /usr/share/doc/bzr/html by default. The 
tutorial is a good place to start. The bzr command also comes with built-in help: 

$ bzr help 

To learn more about the foo command: 
$ bzr help foo 

1.4. Launchpad Integration 

While highly useful as a stand-alone system, Bazaar has good, optional integration with Launchpad 1 , 
the collaborative development system used by Canonical and the broader open source community 
to manage and extend Ubuntu itself. For information on how Bazaar can be used with Launchpad to 
collaborate on open source projects, see http://bazaar-vcs.org/LaunchpadIntegration 2 . 



' https://launchpad.net/ 



9 

http://bazaar-vcs.org/LaunchpadIntegration/ 
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2. Git 



Git is an open source distributed version control system originally developped by Linus Torvalds to 
support the development of the linux kernel. Every Git working directory is a full-fledged repository 
with complete history and full version tracking capabilities, not dependent on network access or a 
central server. 



2.1. Installation 



The git version control system is installed with the following command 



sudo apt-get install git 

2.2. Configuration 

Every git user should first introduce himself to git, by running these two commands: 



git config --global user. email "you@example.com" 
git config --global user. name "Your Name" 

2.3. Basic usage 

The above is already sufficient to use git in a distributed and secure way, provided users have access 
to the machine assuming the server role via SSH. On the server machine, creating a new repository 
can be done with 



git init --bare /path/to/repository 



l%— I This creates a bare repository, that cannot be used to edit files directly. If you would rather 
have a working copy of the contents of the repository on the server, ommit the —bare option. 

Any client with ssh access to the machine can from then on clone the repository with 



git clone username@hostname : /path/to/repository 

Once cloned to the client's machine, the client can edit files, then commit and share them with: 



cd /path/to/repository 
#(edit some files 

git commit -a # Commit all changes to the local version of the repository 

git push origin master # Push changes to the server's version of the repository 

2.4. Installing a gitolite server 

While the above is sufficient to create, clone and edit repositories, users wanting to install git on 
a server will most likely want to have git work like a more traditional source control management 
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server, with multiple users and access rights management. The suggested solution is to install gitolite 
with the following command: 

sudo apt-get install gitolite 

2.5. Gitolite configuration 

Configuration of the gitolite server is a little different that most other servers on Unix-like systems. 
Instead of the traditional configuration files in /etc/, gitolite stores its configuration in a git repository. 
The first step to configuring a new installation is therefore to allow access to the configuration 
repository. 

First of all, let's create a user for gitolite to be accessed as. 

sudo adduser — system — shell /bin/bash — group — disabled-password — home /home/git git 

Now we want to let gitolite know about the repository administrator's public SSH key. This assumes 
that the current user is the repository administrator. 

cp ~/.ssh/id_rsa.pub /tmp/$ (whoami) .pub 

Let's switch to the git user and import the administrator's key into gitolite. 

sudo su - git 
gl-setup /tmp/*.pub 

Gitolite will allow you to make initial changes to its configuration file during the setup process. You 
can now clone and modify the gitolite configuration repository from your administrator user (the 
user whose public SSH key you imported). Switch back to that user, then clone the configuration 
repository: 

exit 

git clone git@$IP_ADDRESS:gitolite-admin.git 
cd gitolite-admin 

The gitolite-admin contains two subdirectories, "conf" and "keydir". The configuration files are in the 
conf dir, and the keydir directory contains the list of user's public SSH keys. 

2.6. Managing gitolite users and repositories 

Adding new users to gitolite is simple: just obtain their public SSH key and add it to the keydir 
directory as $DESIRED_USER_NAME.pub. Note that the gitolite usernames don't have to match 
the system usernames - they are only used in the gitolite configuration file to manage access control. 
Similarly, users are deleted by deleting their public key file. After each change, do not forget to 
commit the changes to git, and push the changes back to the server with 
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git commit -a 

git push origin master 

Repositories are managed by editing the conf/gitolite.conf file. The syntax is space separated, and 
simply specifies the list of repositories followed by some access rules. The following is a default 
example 

repo gitolite-admin 

RW+ = admin 

R = alice 

repo projectl 

RW+ = alice 

RW = bob 

R = denise 

2.7. Using your server 

To use the newly created server, users have to have the gitolite admin import their public key into 
the gitolite configuration repository, they can then access any project they have access to with the 
following command: 

git clone git@$SERVER_IP : $PROJECT_NAME . git 

Or add the server's project as a remote for an existing git repository: 

git remote add gitolite git@$SERVER_IP : $PROJECT_NAME . git 
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3. Subversion 

Subversion is an open source version control system. Using Subversion, you can record the history of 
source files and documents. It manages files and directories over time. A tree of files is placed into a 
central repository. The repository is much like an ordinary file server, except that it remembers every 
change ever made to files and directories. 

3.1. Installation 

To access Subversion repository using the HTTP protocol, you must install and configure a web 
server. Apache2 is proven to work with Subversion. Please refer to the HTTP subsection in the 
Apache2 section to install and configure Apache2. To access the Subversion repository using the 
HTTPS protocol, you must install and configure a digital certificate in your Apache 2 web server. 
Please refer to the HTTPS subsection in the Apache2 section to install and configure the digital 
certificate. 

To install Subversion, run the following command from a terminal prompt: 
sudo apt-get Install subversion apache2 libapache2-svn 

3.2. Server Configuration 

This step assumes you have installed above mentioned packages on your system. This section 
explains how to create a Subversion repository and access the project. 

3.2.1. Create Subversion Repository 

The Subversion repository can be created using the following command from a terminal prompt: 

svnadmin create /path/to/repos /project 

3.2.2. Importing Files 

Once you create the repository you can import files into the repository. To import a directory, enter 
the following from a terminal prompt: 

svn import /path/to/import/directory f ile: ///path/to/repos /project 

3.3. Access Methods 

Subversion repositories can be accessed (checked out) through many different methods -on local 
disk, or through various network protocols. A repository location, however, is always a URL. The 
table describes how different URL schemes map to the available access methods. 
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Table 17.1. Access Methods 



Schema 


Access Method 


file:// 


direct repository access (on local disk) 


http:// 


Access via WebDAV protocol to Subversion-aware Apache2 web server 


https:// 


Same as http://, but with SSL encryption 


svn:// 


Access via custom protocol to an svnserve server 


svn+ssh:// 


Same as svn://, but through an SSH tunnel 



In this section, we will see how to configure Subversion for all these access methods. Here, we cover 
the basics. For more advanced usage details, refer to the svn book 3 . 

3.3.1. Direct repository access (file://) 

This is the simplest of all access methods. It does not require any Subversion server process to be 
running. This access method is used to access Subversion from the same machine. The syntax of the 
command, entered at a terminal prompt, is as follows: 



svn co f ile: ///path/to/repos /project 

or 



svn co f ile: //localhost/path/to/repos/project 

If you do not specify the hostname, there are three forward slashes (///) — two for the 
protocol (file, in this case) plus the leading slash in the path. If you specify the hostname, 
you must use two forward slashes (//). 

The repository permissions depend on filesystem permissions. If the user has read/write permission, 
he can checkout from and commit to the repository. 

3.3.2. Access via WebDAV protocol (http://) 

To access the Subversion repository via WebDAV protocol, you must configure your Apache 2 web 
server. Add the following snippet between the <VirtualHost> and <IVirtualHost> elements in /etc/ 
apache2/sites-available/000-default.conf , or another VirtualHost file: 



<Location /svn> 
DAV svn 

SVNParentPath /path/to/repos 
AuthType Basic 

AuthName "Your repository name" 



http://svnbook.red-bean.com/ 
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AuthUserFile /etc /subversion /pas swd 
Require valid-user 
</Location> 

The above configuration snippet assumes that Subversion repositories are created under / 
path/to/repos directory using svnadmin command and that the HTTP user has sufficent 
access rights to the files (see below). They can be accessible using http://hostname/svn/ 
repos_name url. 

Changing the apache configuration like the above requires to reload the service with the following 
command 



sudo service apache2 reload 

To import or commit files to your Subversion repository over HTTP, the repository should be owned 
by the HTTP user. In Ubuntu systems, the HTTP user is www-data. To change the ownership of the 
repository files enter the following command from terminal prompt: 



sudo chown -R www-data: www-data /path/to/repos 



By changing the ownership of repository as www-data you will not be able to import or 
commit files into the repository by running svn import file:/// command as any user other 
than www-data. 



Next, you must create the /etc/subversion/passwd file that will contain user authentication details. 
To create a file issue the following command at a command prompt (which will create the file and add 
the first user): 



sudo htpasswd -c /etc/subversion/passwd username 

To add additional users omit the "-c" option as this option replaces the old file. Instead use this form: 



sudo htpasswd /etc/subversion/passwd username 

This command will prompt you to enter the password. Once you enter the password, the user is added. 
Now, to access the repository you can run the following command: 

svn co http: //servername/svn 

^yjj^. The password is transmitted as plain text. If you are worried about password snooping, you 
are advised to use SSL encryption. For details, please refer next section. 

3.3.3. Access via WebDAV protocol with SSL encryption (https://) 

Accessing Subversion repository via WebDAV protocol with SSL encryption (https://) is similar 
to http:// except that you must install and configure the digital certificate in your Apache2 web 



277 



Version Control System 



server. To use SSL with Subversion add the above Apache2 configuration to /etc/apache2/ 
sites-available/def ault-ssl . conf . For more information on setting up Apache2 with SSL see 
Section 13, "HTTPS Configuration" [p. 191 ]. 

You can install a digital certificate issued by a signing authority. Alternatively, you can install your 
own self-signed certificate. 

This step assumes you have installed and configured a digital certificate in your Apache 2 web server. 
Now, to access the Subversion repository, please refer to the above section! The access methods are 
exactly the same, except the protocol. You must use https:// to access the Subversion repository. 

3.3.4. Access via custom protocol (svn://) 

Once the Subversion repository is created, you can configure the access control. You can edit the / 
path/to/repos/project/conf /svnserve . conf file to configure the access control. For example, to 
set up authentication, you can uncomment the following lines in the configuration file: 

# [general] 

# password-db = passwd 

After uncommenting the above lines, you can maintain the user list in the passwd file. So, edit the file 
passwd in the same directory and add the new user. The syntax is as follows: 

username = password 

For more details, please refer to the file. 

Now, to access Subversion via the svn:// custom protocol, either from the same machine or a different 
machine, you can run svnserver using svnserve command. The syntax is as follows: 

$ svnserve -d — foreground -r /path/to/repos 

# -d — daemon mode 

# --foreground -- run in foreground (useful for debugging) 

# -r — root of directory to serve 

For more usage details, please refer to: 
$ svnserve — help 

Once you run this command, Subversion starts listening on default port (3690). To access the project 
repository, you must run the following command from a terminal prompt: 

svn co svn: //hostname /project project — username user_name 

Based on server configuration, it prompts for password. Once you are authenticated, it checks out 
the code from Subversion repository. To synchronize the project repository with the local copy, you 
can run the update sub-command. The syntax of the command, entered at a terminal prompt, is as 
follows: 
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cd project_dir ; svn update 

For more details about using each Subversion sub-command, you can refer to the manual. For 
example, to learn more about the co (checkout) command, please run the following command from a 
terminal prompt: 

svn co help 

3.3.5. Access via custom protocol with SSH encryption (svn+ssh://) 

The configuration and server process is same as in the svn:// method. For details, please refer to the 
above section. This step assumes you have followed the above step and started the Subversion server 
using svnserve command. 

It is also assumed that the ssh server is running on that machine and that it is allowing incoming 
connections. To confirm, please try to login to that machine using ssh. If you can login, everything is 
perfect. If you cannot login, please address it before continuing further. 

The svn+ssh:// protocol is used to access the Subversion repository using SSL encryption. The 
data transfer is encrypted using this method. To access the project repository (for example with a 
checkout), you must use the following command syntax: 



svn co svn+ssh: //ssh_username@hostname/path/to/repos/project 

l%— I You must use the full path (/path/to/repos/project) to access the Subversion repository using 
this access method. 



Based on server configuration, it prompts for password. You must enter the password you use to login 
via ssh. Once you are authenticated, it checks out the code from the Subversion repository. 
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3 https://help.ubuntu.com/community/EasyBazaar 
https://help.ubuntu.com/community/Subversion 
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Chapter 18. Samba 

Computer networks are often comprised of diverse systems, and while operating a network made up 
entirely of Ubuntu desktop and server computers would certainly be fun, some network environments 
must consist of both Ubuntu and Microsoft® Windows® systems working together in harmony. This 
section of the Ubuntu Server Guide introduces principles and tools used in configuring your Ubuntu 
Server for sharing network resources with Windows computers. 
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1. Introduction 

Successfully networking your Ubuntu system with Windows clients involves providing and 
integrating with services common to Windows environments. Such services assist the sharing of data 
and information about the computers and users involved in the network, and may be classified under 
three major categories of functionality: 

• File and Printer Sharing Services. Using the Server Message Block (SMB) protocol to facilitate 
the sharing of files, folders, volumes, and the sharing of printers throughout the network. 

• Directory Services. Sharing vital information about the computers and users of the network with 
such technologies as the Lightweight Directory Access Protocol (LDAP) and Microsoft Active 
Directory®. 

• Authentication and Access. Establishing the identity of a computer or user of the network and 
determining the information the computer or user is authorized to access using such principles and 
technologies as file permissions, group policies, and the Kerberos authentication service. 

Fortunately, your Ubuntu system may provide all such facilities to Windows clients and share 
network resources among them. One of the principal pieces of software your Ubuntu system includes 
for Windows networking is the Samba suite of SMB server applications and tools. 

This section of the Ubuntu Server Guide will introduce some of the common Samba use cases, 
and how to install and configure the necessary packages. Additional detailed documentation and 
information on Samba can be found on the Samba website 1 . 



http://www.samba.org 
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2. File Server 

One of the most common ways to network Ubuntu and Windows computers is to configure Samba as 
a File Server. This section covers setting up a Samba server to share files with Windows clients. 

The server will be configured to share files with any client on the network without prompting for a 
password. If your environment requires stricter Access Controls see Section 4, "Securing File and 
Print Server" [p. 288] 

2.1. Installation 

The first step is to install the samba package. From a terminal prompt enter: 



sudo apt-get install samba 

That's all there is to it; you are now ready to configure Samba to share files. 

2.2. Configuration 

The main Samba configuration file is located in /etc/samba/smb.conf . The default configuration file 
has a significant amount of comments in order to document various configuration directives. 

I%— I Not all the available options are included in the default configuration file. See the smb . conf 
man page or the Samba HOWTO Collection for more details. 

1 . First, edit the following key/value pairs in the [global] section of /etc/samba/smb . conf: 

workgroup = EXAMPLE 
security = user 

The security parameter is farther down in the [global] section, and is commented by default. 
Also, change EXAMPLE to better match your environment. 

2. Create a new section at the bottom of the file, or uncomment one of the examples, for the 
directory to be shared: 



[ share ] 

comment = Ubuntu File Server Share 
path = /srv/samba/share 
browsable = yes 
guest ok = yes 
read only = no 
create mask = 0755 

• comment: a short description of the share. Adjust to fit your needs. 



http://samba.org/samba/docs/man/Samba-HOWTO-Collection/ 
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• path: the path to the directory to share. 

This example uses /srv/ samba/ sharename because, according to the Filesystem Hierarchy 
Standard (FHS), /srv 3 is where site-specific data should be served. Technically Samba shares 
can be placed anywhere on the filesystem as long as the permissions are correct, but adhering 
to standards is recommended. 

• browsable: enables Windows clients to browse the shared directory using Windows Explorer. 

• guest ok: allows clients to connect to the share without supplying a password. 

• read only: determines if the share is read only or if write privileges are granted. Write 
privileges are allowed only when the value is no, as is seen in this example. If the value is yes, 
then access to the share is read only. 

• create mask: determines the permissions new files will have when created. 

3. Now that Samba is configured, the directory needs to be created and the permissions changed. 
From a terminal enter: 



sudo mkdir -p /srv/samba/share 

sudo chown nobody . nogroup /srv/samba/share/ 

j^-j The -p switch tells mkdir to create the entire directory tree if it doesn't exist. 

4. Finally, restart the samba services to enable the new configuration: 

sudo restart smbd 
sudo restart nmbd 

Once again, the above configuration gives all access to any client on the local network. For a 
more secure configuration see Section 4, "Securing File and Print Server" [p. 288]. 

From a Windows client you should now be able to browse to the Ubuntu file server and see the shared 
directory. If your client doesn't show your share automatically, try to access your server by its IP 
address, e.g. W192. 168.1 .1 , in a Windows Explorer window. To check that everything is working try 
creating a directory from Windows. 

To create additional shares simply create new [dir] sections in /etc/samba/smb.conf , and restart 
Samba. Just make sure that the directory you want to share actually exists and the permissions are 
correct. 

The file share named "[share]" and the path /srv/samba/share are just examples. Adjust 
the share and path names to fit your environment. It is a good idea to name a share after a 
directory on the file system. Another example would be a share name of [qa] with a path of 
/srv/samba/qa. 



3 http://www.pathname.eom/fhs/pub/flis-2.3.html#SRVDATAFORSERVICESPROVIDEDBYSYSTEM 
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2.3. Resources 

• For in depth Samba configurations see the Samba HOWTO Collection 4 

• The guide is also available in printed format 5 . 

• O'Reilly's Using Samba 6 is another good reference. 

• The Ubuntu Wiki Samba 1 page. 



http://samba.org/samba/docs/man/Samba-HOWTO-Collection/ 
http://www.amazon.eom/exec/obidos/tg/detail/-/0131882228 
http://www.oreilly.com/catalog/9780596007690/ 
https://help.ubuntu.com/community/Samba 
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3. Print Server 

Another common use of Samba is to configure it to share printers installed, either locally or over the 
network, on an Ubuntu server. Similar to Section 2, "File Server" [p. 283] this section will configure 
Samba to allow any client on the local network to use the installed printers without prompting for a 
username and password. 

For a more secure configuration see Section 4, "Securing File and Print Server" [p. 288]. 

3.1. Installation 

Before installing and configuring Samba it is best to already have a working CUPS installation. See 
Section 4, "CUPS - Print Server" [p. 234] for details. 

To install the samba package, from a terminal enter: 
sudo apt-get install samba 

3.2. Configuration 

After installing samba edit /etc/samba/smb.conf . Change the workgroup attribute to what is 
appropriate for your network, and change security to user: 

workgroup = EXAMPLE 
security = user 
In the [printers] section change the guest ok option to yes: 

browsable = yes 
guest ok = yes 

After editing smb.conf restart Samba: 

sudo restart smbd 
sudo restart nmbd 

The default Samba configuration will automatically share any printers installed. Simply install the 
printer locally on your Windows clients. 

3.3. Resources 

• For in depth Samba configurations see the Samba HOWTO Collection' 

http://samba.org/samba/docs/rnan/Samba-HOWTO-Collection/ 
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• The guide is also available in printed format 9 . 

• O'Reilly's Using Samba 0 is another good reference. 

• Also, see the CUPS Website 11 for more information on configuring CUPS. 

• The Ubuntu Wiki Samba 12 page. 



http://www.amazon.eom/exec/obidos/tg/detail/-/0131882228 

3 http://www.oreilly.com/catalog/9780596007690/ 

' http://www.cups.org/ 

" https://help.ubuntu.com/community/Samba 
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4. Securing File and Print Server 

4.1 . Samba Security Modes 

There are two security levels available to the Common Internet Filesystem (CIFS) network protocol 
user-level and share-level. Samba's security mode implementation allows more flexibility, providing 
four ways of implementing user-level security and one way to implement share-level: 

• security = user: requires clients to supply a username and password to connect to shares. Samba 
user accounts are separate from system accounts, but the libpam-smbpass package will sync system 
users and passwords with the Samba user database. 

• security = domain: this mode allows the Samba server to appear to Windows clients as a Primary 
Domain Controller (PDC), Backup Domain Controller (BDC), or a Domain Member Server 
(DMS). See Section 5, "As a Domain Controller" [p. 293] for further information. 

• security = ADS: allows the Samba server to join an Active Directory domain as a native member. 
See Section 6, "Active Directory Integration" [p. 297] for details. 

• security = server: this mode is left over from before Samba could become a member server, and 
due to some security issues should not be used. See the Server Security 13, section of the Samba 
guide for more details. 

• security = share: allows clients to connect to shares without supplying a username and password. 

The security mode you choose will depend on your environment and what you need the Samba server 
to accomplish. 

4.2. Security = User 

This section will reconfigure the Samba file and print server, from Section 2, "File Server" [p. 283] 
and Section 3, "Print Server" [p. 286], to require authentication. 

First, install the libpam-smbpass package which will sync the system users to the Samba user 
database: 

sudo apt-get install libpam-smbpass 




If you chose the Samba Server task during installation libpam-smbpass is already installed. 



Edit /etc/samba/smb.conf , and in the [share] section change: 



guest ok = no 
Finally, restart Samba for the new settings to take effect: 



http://samba.org/samba/docs/man/Samba-HOWTO-Collection/ServerType.html#id349531 
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sudo restart smbd 
sudo restart nmbd 

Now when connecting to the shared directories or printers you should be prompted for a username 
and password. 

If you choose to map a network drive to the share you can check the "Reconnect at Logon" 
check box, which will require you to only enter the username and password once, at least 
until the password changes. 

4.3. Share Security 

There are several options available to increase the security for each individual shared directory. Using 
the [share] example, this section will cover some common options. 

4.3.1 . Groups 

Groups define a collection of computers or users which have a common level of access to particular 
network resources and offer a level of granularity in controlling access to such resources. For 
example, if a group qa is defined and contains the users freda, danika, and rob and a second group 
support is defined and consists of users danika, jeremy, and vincent then certain network resources 
configured to allow access by the qa group will subsequently enable access by freda, danika, and rob, 
but not jeremy or vincent. Since the user danika belongs to both the qa and support groups, she will 
be able to access resources configured for access by both groups, whereas all other users will have 
only access to resources explicitly allowing the group they are part of. 

By default Samba looks for the local system groups defined in /etc/group to determine which 
users belong to which groups. For more information on adding and removing users from groups see 
Section 1.2, "Adding and Deleting Users" [p. 153]. 

When defining groups in the Samba configuration file, /etc/samba/smb.conf , the recognized syntax 
is to preface the group name with an "@" symbol. For example, if you wished to define a group 
named sysadmin in a certain section of the /etc/samba/smb.conf, you would do so by entering the 
group name as ©sysadmin. 

4.3.2. File Permissions 

File Permissions define the explicit rights a computer or user has to a particular directory, file, or set 
of files. Such permissions may be defined by editing the /etc/samba/smb.conf file and specifying 
the explicit permissions of a defined file share. 

For example, if you have defined a Samba share called share and wish to give read-only permissions 
to the group of users known as qa, but wanted to allow writing to the share by the group called 
sysadmin and the user named vincent, then you could edit the /etc/samba/smb.conf file, and add the 
following entries under the [share] entry: 
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read list = @qa 

write list = @sysadmin, vincent 

Another possible Samba permission is to declare administrative permissions to a particular shared 
resource. Users having administrative permissions may read, write, or modify any information 
contained in the resource the user has been given explicit administrative permissions to. 

For example, if you wanted to give the user melissa administrative permissions to the share example, 
you would edit the /etc/samba/smb.conf file, and add the following line under the [share] entry: 



admin users = melissa 



After editing /etc/samba/smb.conf , restart Samba for the changes to take effect: 



sudo restart smbd 
sudo restart nmbd 

«— I For the read list and write list to work the Samba security mode must not be set to security = 
share 

Now that Samba has been configured to limit which groups have access to the shared directory, the 
filesystem permissions need to be updated. 

Traditional Linux file permissions do not map well to Windows NT Access Control Lists (ACLs). 
Fortunately POSIX ACLs are available on Ubuntu servers providing more fine grained control. For 
example, to enable ACLs on /srv an EXT3 filesystem, edit /etc/f stab adding the acl option: 



UUID=66bcdd2e-8861-4fb0-b7e4-e61c569f el7d /srv ext3 noatime , relatime , acl 0 1 
Then remount the partition: 



sudo mount -v -o remount /srv 

The above example assumes /srv on a separate partition. If /srv, or wherever you have 
configured your share path, is part of the / partition a reboot may be required. 

To match the Samba configuration above the sysadmin group will be given read, write, and execute 
permissions to /srv/samba/share, the qa group will be given read and execute permissions, and the 
files will be owned by the username melissa. Enter the following in a terminal: 



sudo chown -R melissa /srv/samba/share/ 
sudo chgrp -R sysadmin /srv/samba/share/ 
sudo setfacl -R -m g:qa:rx /srv/samba/share/ 

The setfacl command above gives execute permissions to all files in the /srv/samba/share 
directory, which you may or may not want. 
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Now from a Windows client you should notice the new file permissions are implemented. See the acl 
and setfacl man pages for more information on POSIX ACLs. 

4.4. Samba App Armor Profile 

Ubuntu comes with the App Armor security module, which provides mandatory access controls. The 
default AppArmor profile for Samba will need to be adapted to your configuration. For more details 
on using AppArmor see Section 4, "AppArmor" [p. 166]. 

There are default AppArmor profiles for /usr/sbin/smbd and /usr/sbin/nmbd, the Samba daemon 
binaries, as part of the apparmor-profiles packages. To install the package, from a terminal prompt 
enter: 

sudo apt-get install apparmor-profiles apparmor-utils 




This package contains profiles for several other binaries. 



By default the profiles for smbd and nmbd are in complain mode allowing Samba to work without 
modifying the profile, and only logging errors. To place the smbd profile into enforce mode, and have 
Samba work as expected, the profile will need to be modified to reflect any directories that are shared. 

Edit /etc/apparmor.d/usr.sbin.smbd adding information for [share] from the file server example: 

/srv/samba/share/ r, 
/srv/samba/share/** rwkix, 

Now place the profile into enforce and reload it: 
sudo aa-enforce /usr/sbin/smbd 

cat /etc/apparmor.d/usr.sbin.smbd | sudo apparmor_parser -r 

You should now be able to read, write, and execute files in the shared directory as normal, and the 
smbd binary will have access to only the configured files and directories. Be sure to add entries for 
each directory you configure Samba to share. Also, any errors will be logged to /var/iog/syslog. 

4.5. Resources 

• For in depth Samba configurations see the Samba HOWTO Collection 14 

• The guide is also available in printed format 15 . 

• O'Reilly's Using Samba 16 is also a good reference. 

• Chapter 18 17 of the Samba HOWTO Collection is devoted to security. 

http://samba.org/samba/docs/man/Samba-HOWTO-Collection/ 

15 http://www.amazon.eom/exec/obidos/tg/detail/-/0131882228 

16 http://www.oreilly.com/catalog/9780596007690/ 
17 

http://samba.org/samba/docs/man/Samba-HOWTO-Collection/securing-samba.html 



291 



Samba 



• For more information on Samba and ACLs see the Samba ACLs page 18 . 



The Ubuntu Wiki Samba 19 page. 



18 http://samba.org/samba/docs/man/Samba-HOWTO-Collection/ AccessControls.html#id397568 
19 

https://help.ubuntu.com/community/Samba 
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5. As a Domain Controller 

Although it cannot act as an Active Directory Primary Domain Controller (PDC), a Samba server 
can be configured to appear as a Windows NT4-style domain controller. A major advantage of this 
configuration is the ability to centralize user and machine credentials. Samba can also use multiple 
backends to store the user information. 

5.1 . Primary Domain Controller 

This section covers configuring Samba as a Primary Domain Controller (PDC) using the default 
smbpasswd backend. 

1. First, install Samba, and libpam-smbpass to sync the user accounts, by entering the following in 
a terminal prompt: 

sudo apt-get install samba libpam-smbpass 

2. Next, configure Samba by editing /etc/samba/smb.conf . The security mode should be set to 
user, and the workgroup should relate to your organization: 

workgroup = EXAMPLE 
security = user 

3. In the commented "Domains" section add or uncomment the following (the last line has been 
split to fit the format of this document): 

domain logons = yes 

logon path = \\%N\%U\prof ile 

logon drive = H: 

logon home = \\%N\%U 

logon script = logon.cmd 

add machine script = sudo /usr/sbin/useradd -N -g machines -c Machine -d 
/var/lib/samba -s /bin/false %u 




If you wish to not use Roaming Profiles leave the logon home and logon path options 
commented. 



• domain logons: provides the netlogon service causing Samba to act as a domain controller. 

• logon path: places the user's Windows profile into their home directory. It is also possible to 
configure a [profiles] share placing all profiles under a single directory. 

• logon drive: specifies the home directory local path. 

• logon home: specifies the home directory location. 

• logon script: determines the script to be run locally once a user has logged in. The script needs 
to be placed in the [netlogon] share. 
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• add machine script: a script that will automatically create the Machine Trust Account needed 
for a workstation to join the domain. 

In this example the machines group will need to be created using the addgroup utility see 
Section 1.2, "Adding and Deleting Users" [p. 153] for details. 

4. Uncomment the [homes] share to allow the logon home to be mapped: 
[ homes ] 

comment = Home Directories 
browseable = no 
read only = no 
create mask = 0700 
directory mask = 0700 
valid users = %S 

5. When configured as a domain controller a [netlogon] share needs to be configured. To enable the 
share, uncomment: 

[netlogon] 

comment = Network Logon Service 
path = /srv/samba/netlogon 
guest ok = yes 
read only = yes 
share modes = no 



6. Now create the netlogon directory, and an empty (for now) logon . cmd script file: 

sudo mkdir -p /srv/samba/netlogon 

sudo touch /srv/samba/netlogon/logon.cmd 

You can enter any normal Windows logon script commands in iogon.cmd to customize the 
client's environment. 

7. Restart Samba to enable the new domain controller: 

sudo restart smbd 
sudo restart nmbd 

8. Lastly, there are a few additional commands needed to setup the appropriate rights. 

With root being disabled by default, in order to join a workstation to the domain, a system group 
needs to be mapped to the Windows Domain Admins group. Using the net utility, from a terminal 
enter: 



http://www.pathname.eom/fhs/pub/flis-2.3.html#SRVDATAFORSERVICESPROVIDEDBYSYSTEM 




The original netlogon share path is /home/samba/netiogon, but according to the 
Filesystem Hierarchy Standard (FHS), Isrv 20 is the correct location for site-specific data 
provided by the system. 
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sudo net groupmap add ntgroup=" Domain Admins" unixgroup=sysadmin rid=512 type=d 



Change sysadmin to whichever group you prefer. Also, the user used to join the domain 
needs to be a member of the sysadmin group, as well as a member of the system admin 
group. The admin group allows sudo use. 

If the user does not have Samba credentials yet, you can add them with the smbpasswd 
utility, change the sysadmin username appropriately: 

sudo smbpasswd -a sysadmin 



Also, rights need to be explicitly provided to the Domain Admins group to allow the add machine 
script (and other admin functions) to work. This is achieved by executing: 

net rpc rights grant -U sysadmin " EXAMPLE \ Domain Admins" SeMachineAccountPrivilege \ 
SePrintOperatorPrivilege SeAddUsersPrivilege SeDiskOperatorPrivilege \ 
SeRemoteShutdownPrivilege 

9. You should now be able to join Windows clients to the Domain in the same manner as joining 
them to an NT4 domain running on a Windows server. 

5.2. Backup Domain Controller 

With a Primary Domain Controller (PDC) on the network it is best to have a Backup Domain 
Controller (BDC) as well. This will allow clients to authenticate in case the PDC becomes 
unavailable. 

When configuring Samba as a BDC you need a way to sync account information with the PDC. There 
are multiple ways of accomplishing this scp, rsync, or by using LDAP as the passdb backend. 

Using LDAP is the most robust way to sync account information, because both domain controllers 
can use the same information in real time. However, setting up a LDAP server may be overly 
complicated for a small number of user and computer accounts. See Section 2, "Samba and 
LDAP" [p. 117] for details. 

1. First, install samba and libpam-smbpass. From a terminal enter: 

sudo apt-get install samba libpam-smbpass 

2. Now, edit /etc/samba/smb . conf and uncomment the following in the [global ]: 

workgroup = EXAMPLE 




security = user 



3. 



In the commented Domains uncomment or add: 
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domain logons = yes 
domain master = no 

4. Make sure a user has rights to read the files in /var/lib/samba. For example, to allow users in 
the admin group to scp the files, enter: 

sudo chgrp -R admin /var/lib/samba 

5. Next, sync the user accounts, using scp to copy the /var/lib/samba directory from the PDC: 

sudo scp -r username@pdc : /var/lib/samba /var/lib 

«— . Replace username with a valid username and pdc with the hostname or IP Address of 
your actual PDC. 

6. Finally, restart samba: 

sudo restart smbd 
sudo restart nmbd 

You can test that your Backup Domain controller is working by stopping the Samba daemon on the 
PDC, then trying to login to a Windows client joined to the domain. 

Another thing to keep in mind is if you have configured the logon home option as a directory on the 
PDC, and the PDC becomes unavailable, access to the user's Home drive will also be unavailable. For 
this reason it is best to configure the logon home to reside on a separate file server from the PDC and 
BDC. 

5.3. Resources 

• For in depth Samba configurations see the Samba HOWTO Collection 21 

• The guide is also available in printed format 22 . 

• O'Reilly's Using Samba 21 ' is also a good reference. 

• Chapter 4 2A of the Samba HOWTO Collection explains setting up a Primary Domain Controller. 

• Chapter 5 25 of the Samba HOWTO Collection explains setting up a Backup Domain Controller. 

• The Ubuntu Wiki Samba 26 page. 



http://samba.org/samba/docs/man/Samba-HOWTO-Collection/ 
http://www .amazon .com/exec/obidos/tg/detail/-/0 131882228 
http://www.oreilly.com/catalog/9780596007690/ 

http://samba.org/samba/docs/man/Samba-HOWTO-Collection/samba-pdc.html 
http://us3.samba.org/samba/docs/man/Samba-HOWTO-Collection/samba-bdc.html 
https ://help .ubuntu .com/community/Samba 
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6. Active Directory Integration 

6.1 . Accessing a Samba Share 

Another, use for Samba is to integrate into an existing Windows network. Once part of an Active 
Directory domain, Samba can provide file and print services to AD users. 

The simplest way to join an AD domain is to use Likewise-open. For detailed instructions see the 
Likewise Open documentation 21 . 

Once part of the Active Directory domain, enter the following command in the terminal prompt: 

sudo apt-get Install samba smbfs smbcllent 

Next, edit /etc/samba/smb.conf changing: 

workgroup = EXAMPLE 

security = ads 
realm = EXAMPLE.COM 

idmap backend = lwopen 
idmap uid = 50-9999999999 
idmap gid = 50-9999999999 

Restart samba for the new settings to take effect: 

sudo restart smbd 
sudo restart nmbd 

You should now be able to access any Samba shares from a Windows client. However, be sure to give 
the appropriate AD users or groups access to the share directory. See Section 4, "Securing File and 
Print Server" [p. 288] for more details. 

6.2. Accessing a Windows Share 

Now that the Samba server is part of the Active Directory domain you can access any Windows server 
shares: 

• To mount a Windows file share enter the following in a terminal prompt: 
mount. cifs //fsOl . example . com/share mount_point 

It is also possible to access shares on computers not part of an AD domain, but a username and 
password will need to be provided. 



http://www.beyondtrust.com/Technical-Support/Downloads/files/pbiso/Manuals/ubuntu-active-directory.html 
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• To mount the share during boot place an entry in /etc/f stab, for example: 

//192 . 168 . 0 . 5/share /mnt /windows cifs auto , username=steve , password=secret , rw 0 0 

• Another way to copy files from a Windows server is to use the smbclient utility. To list the files in 
a Windows share: 

smbclient //fsOl . example . com/share -k -c "Is" 

• To copy a file from the share, enter: 

smbclient //fsOl . example . com/share -k -c "get file.txt" 

This will copy the file . txt into the current directory. 

• And to copy a file to the share: 

smbclient //fsOl . example . com/share -k -c "put /etc/hosts hosts" 

This will copy the /etc/hosts to //fsOl .example.com/share/hosts. 

• The -c option used above allows you to execute the smbclient command all at once. This is useful 
for scripting and minor file operations. To enter the smb: \> prompt, a FTP like prompt where you 
can execute normal file and directory commands, simply execute: 

smbclient //fsOl . example . com/share -k 

Replace all instances of fsOl .example .com/ share , 1 1 192 .168 .0 .5/share , 
username=steve,password=secret, and file. txt with your server's IP, hostname, share name, 
file name, and an actual username and password with rights to the share. 

6.3. Resources 



For more smbclient options see the man page: man smbclient, also available online 
The mount .cifs man page 29 is also useful for more detailed information. 
The Ubuntu Wiki Samba 30 page. 



28 



http://manpages.ubuntu.eom/manpages/trusty/en/manl/smbclient.l.html 
http://manpages .ubuntu.com/manpages/trusty/en/man8/mount .cifs .8 .html 
https ://help .ubuntu .com/community/Samba 
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Chapter 19. Backups 

There are many ways to backup an Ubuntu installation. The most important thing about backups is to 
develop a backup plan consisting of what to backup, where to back it up to, and how to restore it. 

The following sections discuss various ways of accomplishing these tasks. 
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1. Shell Scripts 

One of the simplest ways to backup a system is using a shell script. For example, a script can be used 
to configure which directories to backup, and pass those directories as arguments to the tar utility, 
which creates an archive file. The archive file can then be moved or copied to another location. The 
archive can also be created on a remote file system such as an NFS mount. 

The tar utility creates one archive file out of many files or directories, tar can also filter the files 
through compression utilities, thus reducing the size of the archive file. 

1.1. Simple Shell Script 

The following shell script uses tar to create an archive file on a remotely mounted NFS file system. 
The archive filename is determined using additional command line utilities. 

#!/bin/sh 
# 

# Backup to NFS mount script. 
# 



# What to backup. 

backup_f iles=" /home /var/spool/mail /etc /root /boot /opt" 

# Where to backup to. 
dest="/mnt/backup" 

# Create archive filename. 
day=$(date +%A) 
hostname=$ (hostname -s) 
archive_f ile= " $hostname-$day . tgz " 

# Print start status message. 

echo "Backing up $backup_f iles to $dest/$archive_f ile" 

date 

echo 

# Backup the files using tar. 

tar czf $dest/$archive_f ile $backup_f iles 

# Print end status message, 
echo 

echo "Backup finished" 
date 

# Long listing of files in $dest to check file sizes. 
Is -lh $dest 
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• $backupjiles: a variable listing which directories you would like to backup. The list should be 
customized to fit your needs. 

• $day: a variable holding the day of the week (Monday, Tuesday, Wednesday, etc). This is used to 
create an archive file for each day of the week, giving a backup history of seven days. There are 
other ways to accomplish this including using the date utility. 

• $hostname: variable containing the short hostname of the system. Using the hostname in the 
archive filename gives you the option of placing daily archive files from multiple systems in the 
same directory. 

• $archivejile: the full archive filename. 

• $dest: destination of the archive file. The directory needs to be created and in this case mounted 
before executing the backup script. See Section 2, "Network File System (NFS) " [p. 229] for 
details of using NFS. 

• status messages: optional messages printed to the console using the echo utility. 

• tar czf $destl$ar chive Jile $backupjiles: the tar command used to create the archive file. 

• c: creates an archive. 

• z: filter the archive through the gzip utility compressing the archive. 

• /: output to an archive file. Otherwise the tar output will be sent to STDOUT. 

• Is -Ih $dest: optional statement prints a -/ long listing in -h human readable format of the destination 
directory. This is useful for a quick file size check of the archive file. This check should not replace 
testing the archive file. 

This is a simple example of a backup shell script; however there are many options that can be 
included in such a script. See Section 1.4, "References" [p. 303] for links to resources providing 
more in-depth shell scripting information. 

1.2. Executing the Script 

1 .2.1 . Executing from a Terminal 

The simplest way of executing the above backup script is to copy and paste the contents into a file, 
backup . sh for example. Then from a terminal prompt: 

sudo bash backup. sh 

This is a great way to test the script to make sure everything works as expected. 

1.2.2. Executing with cron 

The cron utility can be used to automate the script execution. The cron daemon allows the execution 
of scripts, or commands, at a specified time and date. 

cron is configured through entries in a crontab file, crontab files are separated into fields: 
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• m h dom mon dow command 

• m: minute the command executes on, between 0 and 59. 

• h: hour the command executes on, between 0 and 23. 

• dom: day of month the command executes on. 

• mon: the month the command executes on, between 1 and 12. 

• dow: the day of the week the command executes on, between 0 and 7. Sunday may be specified by 
using 0 or 7, both values are valid. 

• command: the command to execute. 

To add or change entries in a crontab file the crontab -e command should be used. Also, the contents 
of a crontab file can be viewed using the crontab -1 command. 

To execute the backup.sh script listed above using cron. Enter the following from a terminal prompt: 



sudo crontab -e 



«— i Using sudo with the crontab -e command edits the root user's crontab. This is necessary if 
you are backing up directories only the root user has access to. 

Add the following entry to the crontab file: 



# m h dom mon dow command 

0 0*** bash /usr/local/bin/backup . sh 

The backup.sh script will now be executed every day at 12:00 am. 



The backup.sh script will need to be copied to the /usr/iocai/bin/ directory in order for 
this entry to execute properly. The script can reside anywhere on the file system, simply 
change the script path appropriately. 

For more in-depth crontab options see Section 1.4, "References" [p. 303]. 

1 .3 . Restoring from the Archive 



Once an archive has been created it is important to test the archive. The archive can be tested by 
listing the files it contains, but the best test is to restore a file from the archive. 

• To see a listing of the archive contents. From a terminal prompt type: 



tar -tzvf /mnt /backup/host-Monday . tgz 

• To restore a file from the archive to a different directory enter: 



tar -xzvf /mnt/backup/host-Monday . tgz -C /tmp etc/hosts 
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The -C option to tar redirects the extracted files to the specified directory. The above example will 
extract the /etc/hosts file to /tmp/etc/hosts. tar recreates the directory structure that it contains. 

Also, notice the leading "/" is left off the path of the file to restore. 

• To restore all files in the archive enter the following: 

cd / 

sudo tar -xzvf /mnt/backup/host-Monday.tgz 

SThis will overwrite the files currently on the file system. 

1.4. References 

• For more information on shell scripting see the Advanced Bash-Scripting Guide 1 

• The book Teach Yourself Shell Programming in 24 Hours 2 is available online and a great resource 
for shell scripting. 

• The CronHowto Wiki Page 3, contains details on advanced cron options. 

• See the GNU tar Manual 4 for more tar options. 

• The Wikipedia Backup Rotation Scheme 5 article contains information on other backup rotation 
schemes. 

• The shell script uses tar to create the archive, but there many other command line utilities that can 
be used. For example: 

• cpio 6 : used to copy files to and from archives. 

• dd 7 : part of the coreutils package. A low level utility that can copy data from one format to 
another. 

• rsnapshoi: a file system snapshot utility used to create copies of an entire file system. 

• rsync 9 : a flexible utility used to create incremental copies of files. 



http://tldp.org/LDP/abs/html/ 
http://safari.samspublishing.com/0672323583 
https ://help .ubuntu .com/community/CronHowto 
http://www.gnu.org/software/tar/manual/index.html 
http://en.wikipedia.org/wiki/Backup_rotation_scheme 
http://www.gnu.org/software/cpio/ 
http://www.gnu.org/software/coreutils/ 
http://www .rsnapshot .org/ 
http://www.samba.org/ftp/rsync/rsync .html 
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2. Archive Rotation 

The shell script in Section 1, "Shell Scripts" [p. 300] only allows for seven different archives. For a 
server whose data doesn't change often, this may be enough. If the server has a large amount of data, a 
more complex rotation scheme should be used. 

2.1. Rotating NFS Archives 

In this section, the shell script will be slightly modified to implement a grandfather-father-son rotation 
scheme (monthly- weekly-daily): 

# The rotation will do a daily backup Sunday through Friday. 

# On Saturday a weekly backup is done giving you four weekly backups a month. 

# The monthly backup is done on the first of the month rotating two monthly backups based on if the 
month is odd or even. 

Here is the new script: 
#! /bin/bash 

#################################### 
# 

# Backup to NFS mount script with 

# grandfather-father-son rotation. 
# 

# What to backup. 

backup_f iles=" /home /var/spool/mail /etc /root /boot /opt" 

# Where to backup to. 
dest=" /mnt/backup" 

# Setup variables for the archive filename. 
day=$(date +%A) 

hostname=$ (hostname -s) 

# Find which week of the month 1-4 it is. 
day_num=$ ( date +%d) 

if ( ( $day_num <= 7 ) ) ; then 

week_f ile=" $hostname-weekl . tgz " 
elif ( ( $day_num > 7 && $day_num <= 14 ) ) ; then 

week_f ile=" $hostname-week2 . tgz " 
elif (( $day_num > 14 && $day_num <= 21 )); then 

week_f ile=" $hostname-week3 . tgz " 
elif (( $day_num > 21 && $day_num < 32 )); then 

week_f ile=" $hostname-week4 . tgz " 

fi 



304 



Backups 



# Find if the Month is odd or even. 
month_num= $ ( date + %m ) 

month=$ ( expr $month_num % 2) 
if [ $month -eq 0 ] ; then 

month_f ile=" $hostname-month2 . tgz " 

else 

month_f ile=" $hostname-monthl . tgz " 

fi 

# Create archive filename, 
if [ $day_num == 1 ] ; then 

archive_f ile=$month_f ile 
elif [ $day != "Saturday" ]; then 

archive_f ile= " $hostname-$day . tgz " 

else 

archive_f ile=$week_f ile 
fi 

# Print start status message. 

echo "Backing up $backup_f iles to $dest/$archive_f ile" 

date 

echo 

# Backup the files using tar. 

tar czf $dest/$archive_f ile $backup_f iles 

# Print end status message, 
echo 

echo "Backup finished" 
date 

# Long listing of files in $dest to check file sizes. 
Is -lh $dest/ 

The script can be executed using the same methods as in Section 1.2, "Executing the Script" [p. 301 ]. 

It is good practice to take backup media off-site in case of a disaster. In the shell script example the 
backup media is another server providing an NFS share. In all likelihood taking the NFS server to 
another location would not be practical. Depending upon connection speeds it may be an option to 
copy the archive file over a WAN link to a server in another location. 

Another option is to copy the archive file to an external hard drive which can then be taken off-site. 
Since the price of external hard drives continue to decrease, it may be cost-effective to use two drives 
for each archive level. This would allow you to have one external drive attached to the backup server 
and one in another location. 

2.2. Tape Drives 

A tape drive attached to the server can be used instead of an NFS share. Using a tape drive simplifies 
archive rotation, and makes taking the media off-site easier as well. 
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When using a tape drive, the filename portions of the script aren't needed because the data is sent 
directly to the tape device. Some commands to manipulate the tape are needed. This is accomplished 
using mt, a magnetic tape control utility part of the cpio package. 

Here is the shell script modified to use a tape drive: 



#! /bin/bash 

#################################### 
# 

# Backup to tape drive script. 
# 

#################################### 



# What to backup. 

backup_f iles=" /home /var/spool/mail /etc /root /boot /opt" 



# Where to backup to. 
dest=" /dev/stO " 



# Print start status message. 

echo "Backing up $backup_f iles to $dest" 

date 

echo 



# Make sure the tape is rewound, 
mt -f $dest rewind 

# Backup the files using tar. 
tar czf $dest $backup_f iles 

# Rewind and eject the tape, 
mt -f $dest rewoffl 

# Print end status message, 
echo 

echo "Backup finished" 
date 

The default device name for a SCSI tape drive is /dev/sto. Use the appropriate device path 
for your system. 

Restoring from a tape drive is basically the same as restoring from a file. Simply rewind the tape and 
use the device path instead of a file path. For example to restore the /etc/hosts file to /tmp/etc/ 
hosts: 



mt -f /dev/stO rewind 

tar -xzf /dev/stO -C /tmp etc/hosts 
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3. Bacula 

Bacula is a backup program enabling you to backup, restore, and verify data across your network. 
There are Bacula clients for Linux, Windows, and Mac OS X - making it a cross-platform network 
wide solution. 

3.1 . Overview 



Bacula is made up of several components and services used to manage which files to backup and 
backup locations: 

• Bacula Director: a service that controls all backup, restore, verify, and archive operations. 

• Bacula Console: an application allowing communication with the Director. There are three versions 
of the Console: 

• Text based command line version. 

• Gnome based GTK+ Graphical User Interface (GUI) interface. 

• wxWidgets GUI interface. 

• Bacula File: also known as the Bacula Client program. This application is installed on machines to 
be backed up, and is responsible for the data requested by the Director. 

• Bacula Storage: the programs that perform the storage and recovery of data to the physical media. 

• Bacula Catalog: is responsible for maintaining the file indexes and volume databases for all files 
backed up, enabling quick location and restoration of archived files. The Catalog supports three 
different databases MySQL, PostgreSQL, and SQLite. 

• Bacula Monitor: allows the monitoring of the Director, File daemons, and Storage daemons. 
Currently the Monitor is only available as a GTK+ GUI application. 

These services and applications can be run on multiple servers and clients, or they can be installed on 
one machine if backing up a single disk or volume. 

3.2. Installation 



l%— I If using MySQL or PostgreSQL as your database, you should already have the services 

we 

available. Bacula will not install them for you. 

There are multiple packages containing the different Bacula components. To install Bacula, from a 
terminal prompt enter: 



sudo apt-get install bacula 

By default installing the bacula package will use a MySQL database for the Catalog. If you want to 
use SQLite or PostgreSQL, for the Catalog, install bacula-director-sqlite3 or bacula-director-pgsql 
respectively. 
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During the install process you will be asked to supply credentials for the database administrator and 
the bacula database owner. The database administrator will need to have the appropriate rights to 
create a database, see Section 1, "MySQL" [p. 205] for more information. 

3.3. Configuration 

Bacula configuration files are formatted based on resources comprising of directives surrounded by 
"{}" braces. Each Bacula component has an individual file in the /etc/bacuia directory. 

The various Bacula components must authorize themselves to each other. This is accomplished using 
the password directive. For example, the Storage resource password in the /etc/bacula/bacula- 
dir.conf file must match the Director resource password in /etc/bacula/bacula-sd.conf . 

By default the backup job named Client 1 is configured to archive the Bacula Catalog. If you plan on 
using the server to backup more than one client you should change the name of this job to something 
more descriptive. To change the name edit /etc/bacula/bacuia-dir .conf : 



# 

# Define the main nightly save backup job 

# By default, this job will back up to disk in 
Job { 

Name = "BackupServer " 
JobDefs = "DefaultJob" 

Write Bootstrap = " /var/lib/bacula/Clientl .bsr " 

} 

The example above changes the job name to BackupServer matching the machine's host 
name. Replace "BackupServer" with your appropriate hostname, or other descriptive name. 

The Console can be used to query the Director about jobs, but to use the Console with a non-root 
user, the user needs to be in the bacula group. To add a user to the bacula group enter the following 
from a terminal: 



sudo adduser $username bacula 



*— I Replace $username with the actual username. Also, if you are adding the current user to the 
group you should log out and back in for the new permissions to take effect. 

3.4. Localhost Backup 

This section describes how to backup specified directories on a single host to a local tape drive. 
• First, the Storage device needs to be configured. Edit /etc/bacula/bacula-sd.conf add: 



Device { 

Name = "Tape Drive" 
Device Type = tape 
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Media Type = DDS-4 
Archive Device = /dev/stO 
Hardware end of medium = No; 

AutomaticMount = yes; # when device opened, read it 

AlwaysOpen = Yes; 
RemovableMedia = yes ; 
RandomAccess = no; 

Alert Command = "sh -c ' tapeinf o -f %c | grep TapeAlert ' " 

} 

The example is for a DDS-4 tape drive. Adjust the "Media Type" and "Archive Device" to match 
your hardware. 

You could also uncomment one of the other examples in the file. 

• After editing /etc/bacula/bacula-sd.conf the Storage daemon will need to be restarted: 

sudo service bacula-sd restart 

• Now add a Storage resource in /etc/bacula/bacula-dir .conf to use the new Device: 

# Definition of "Tape Drive" storage device 
Storage { 

Name = TapeDrive 

# Do not use "localhost" here 

Address = backupserver # N.B. Use a fully qualified name here 

SDPort = 9103 

Password = "Cv70F6pf lt6pBopT4vQOnigDrR0v3LT3Cgkiy jc " 
Device = "Tape Drive" 
Media Type = tape 

} 

The Address directive needs to be the Fully Qualified Domain Name (FQDN) of the server. Change 
backupserver to the actual host name. 

Also, make sure the Password directive matches the password string in /etc/bacula/bacula- 
sd.conf. 

• Create a new FileSet, which will determine what directories to backup, by adding: 



# LocalhostBacup FileSet. 
FileSet { 

Name = "LocalhostFiles " 
Include { 
Options { 

signature = MD5 
compression=GZIP 

} 

File = /etc 
File = /home 
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} 

This FileSet will backup the /etc and /home directories. The Options resource directives configure 
the FileSet to create an MD5 signature for each file backed up, and to compress the files using 
GZIP. 

• Next, create a new Schedule for the backup job: 

# LocalhostBackup Schedule — Daily. 
Schedule { 

Name = "LocalhostDaily " 
Run = Full daily at 00:01 

} 

The job will run every day at 00:01 or 12:01 am. There are many other scheduling options 
available. 

• Finally create the Job: 

# Localhost backup. 
Job { 

Name = "LocalhostBackup" 
JobDefs = "Def aultJob" 
Enabled = yes 
Level = Full 

FileSet = "LocalhostFiles " 
Schedule = "LocalhostDaily" 
Storage = TapeDrive 

Write Bootstrap = " /var/lib/bacula/LocalhostBackup . bsr " 

} 

The job will do a Full backup every day to the tape drive. 

• Each tape used will need to have a Label. If the current tape does not have a label Bacula will send 
an email letting you know. To label a tape using the Console enter the following from a terminal: 

bconsole 

• At the Bacula Console prompt enter: 
label 

• You will then be prompted for the Storage resource: 

Automatically selected Catalog: MyCatalog 

Using Catalog "MyCatalog" 

The defined Storage resources are: 

1: File 

2 : TapeDrive 
Select Storage resource (1-2) :2 
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• Enter the new Volume name: 



Enter new Volume name : Sunday 
Defined Pools: 

1 : Default 

2 : Scratch 

Replace Sunday with the desired label. 
• Now, select the Pool: 



Select the Pool (1-2): 1 

Connecting to Storage daemon TapeDrive at backupserver : 9 103 ... 
Sending label command for Volume "Sunday" Slot 0 ... 



Congratulations, you have now configured Bacula to backup the localhost to an attached tape drive. 

3.5. Resources 

• For more Bacula configuration options refer to the Bacula User's Manual 10 

• The Bacula Home Page 11 contains the latest Bacula news and developments. 

• Also, see the Bacula Ubuntu Wiki 12 page. 



http://www.bacula.org/en/rel-manual/index.html 

http://www.bacula.org/ 

https://help.ubuntu.com/community/Bacula 
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Virtualization is being adopted in many different environments and situations. If you are a developer, 
virtualization can provide you with a contained environment where you can safely do almost any 
sort of development safe from messing up your main working environment. If you are a systems 
administrator, you can use virtualization to more easily separate your services and move them around 
based on demand. 

The default virtualization technology supported in Ubuntu is KVM. KVM requires virtualization 
extensions built into Intel and AMD hardware. Xen is also supported on Ubuntu. Xen can take 
advantage of virtualization extensions, when available, but can also be used on hardware without 
virtualization extensions. Qemu is another popular solution for hardware without virtualization 
extensions. 
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1. libvirt 



The libvirt library is used to interface with different virtualization technologies. Before getting started 
with libvirt it is best to make sure your hardware supports the necessary virtualization extensions for 
KVM. Enter the following from a terminal prompt: 



kvm-ok 



A message will be printed informing you if your CPU does or does not support hardware 
virtualization. 



On many computers with processors supporting hardware assisted virtualization, it is 
necessary to activate an option in the BIOS to enable it. 

1.1. Virtual Networking 



There are a few different ways to allow a virtual machine access to the external network. The 
default virtual network configuration includes bridging and iptables rules implementing usermode 
networking, which uses the SLIRP protocol. Traffic is NATed through the host interface to the 
outside network. 

To enable external hosts to directly access services on virtual machines a different type of bridge than 
the default needs to be configured. This allows the virtual interfaces to connect to the outside network 
through the physical interface, making them appear as normal hosts to the rest of the network. 

1.2. Installation 



To install the necessary packages, from a terminal prompt enter: 



sudo apt-get install qemu-kvm llbvirt-bln 

After installing libvirt-bin, the user used to manage virtual machines will need to be added to the 
libvirtd group. Doing so will grant the user access to the advanced networking options. 

In a terminal enter: 



sudo adduser $USER libvirtd 



*— I If the user chosen is the current user, you will need to log out and back in for the new group 

mi 

membership to take effect. 

You are now ready to install a Guest operating system. Installing a virtual machine follows the same 
process as installing the operating system directly on the hardware. You either need a way to automate 
the installation, or a keyboard and monitor will need to be attached to the physical machine. 
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In the case of virtual machines a Graphical User Interface (GUI) is analogous to using a physical 
keyboard and mouse. Instead of installing a GUI the virt-viewer application can be used to connect 
to a virtual machine's console using VNC. See Section 1.6, "Virtual Machine Viewer" [p. 316] for 
more information. 

There are several ways to automate the Ubuntu installation process, for example using preseeds, 
kickstart, etc. Refer to the Ubuntu Installation Guide 1 for details. 

Yet another way to install an Ubuntu virtual machine is to use uvtool. This application, available as 
of 14.04 allows you to set up specific VM options, execute custom post-install scripts, etc. For details 
see Section 2, "Cloud images and uvtool" [p. 318] 

Libvirt can also be configured work with Xen. For details, see the Xen Ubuntu community page 
referenced below. 

1.3. virt-install 

virt-install is part of the virtinst package. To install it, from a terminal prompt enter: 
sudo apt-get install virtinst 

There are several options available when using virt-install. For example: 
sudo virt-install -n web_devel -r 256 \ 

— disk path=/var/lib/libvirt/images/web_devel . img,bus=virtio, size-4 -c \ 
ubuntu-14.04-server-i386.iso — network network=def ault,model=virtio \ 
— graphics vnc, listen=0 . 0 . 0 . 0 — noautoconsole -v 

• -n web_devel: the name of the new virtual machine will be web_devel in this example. 

• -r 256: specifies the amount of memory the virtual machine will use in megabytes. 

• —disk path=/var/lib/libvirt/images/web_devel.img,size=4: indicates the path to the virtual disk 
which can be a file, partition, or logical volume. In this example a file named web devel . img in 
the /var/lib/libvirt/images/ directory, with a size of 4 gigabytes, and using virtio for the disk bus. 

• -c ubuntu-14.04-server-i386.iso: file to be used as a virtual CDROM. The file can be either an ISO 
file or the path to the host's CDROM device. 

• —network provides details related to the VM's network interface. Here the default network is used, 
and the interface model is configured for virtio. 

• —graphics vnc, ,listen=0, .0.0.0: exports the guest's virtual console using VNC and on all host 
interfaces. Typically servers have no GUI, so another GUI based computer on the Local Area 
Network (LAN) can connect via VNC to complete the installation. 

• —noautoconsole: will not automatically connect to the virtual machine's console. 

• -v: creates a fully virtualized guest. 

1 https://help.ubuntu.com/14.04/installation-guide/ 
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After launching virt-install you can connect to the virtual machine's console either locally using a GUI 
(if your server has a GUI), or via a remote VNC client from a GUI based computer. 

1.4. virt-clone 

The virt-clone application can be used to copy one virtual machine to another. For example: 



sudo virt-clone -o web_devel -n databasedevel -f /path/to/database_devel . img \ 
--connect=qemu : ///system 

• -o: original virtual machine. 

• -n: name of the new virtual machine. 

• path to the file, logical volume, or partition to be used by the new virtual machine. 

• —connect: specifies which hypervisor to connect to. 

Also, use -d or -debug option to help troubleshoot problems with virt-clone. 
I%— I Replace web_devel and database _devel with appropriate virtual machine names. 



1 .5 . Virtual Machine Management 

1.5.1. virsh 

There are several utilities available to manage virtual machines and libvirt. The virsh utility can be 
used from the command line. Some examples: 

• To list running virtual machines: 



virsh -c qemu : ///system list 

• To start a virtual machine: 



virsh -c qemu : ///system start web_devel 

• Similarly, to start a virtual machine at boot: 



virsh -c qemu : ///system autostart web_devel 

• Reboot a virtual machine with: 



virsh -c qemu : ///system reboot web_devel 

• The state of virtual machines can be saved to a file in order to be restored later. The following will 
save the virtual machine state into a file named according to the date: 



virsh -c qemu : ///system save web_devel web_devel-022708 . state 
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Once saved the virtual machine will no longer be running. 

• A saved virtual machine can be restored using: 

virsh -c qemu : ///system restore web_devel-022708 . state 

• To shutdown a virtual machine do: 

virsh -c qemu : ///system shutdown web_devel 

• A CDROM device can be mounted in a virtual machine by entering: 

virsh -c qemu : ///system attach-disk web_devel /dev/cdrom /media/cdrom 



In the above examples replace web_devel with the appropriate virtual machine name, and 



web_devei-022708 . state with a descriptive file name. 
1.5.2. Virtual Machine Manager 

The virt-manager package contains a graphical utility to manage local and remote virtual machines. 
To install virt-manager enter: 

sudo apt-get install virt-manager 

Since virt-manager requires a Graphical User Interface (GUI) environment it is recommended to 
be installed on a workstation or test machine instead of a production server. To connect to the local 
libvirt service enter: 

virt-manager -c qemu : ///system 

You can connect to the libvirt service running on another host by entering the following in a terminal 
prompt: 

virt-manager -c qemu+ssh: //virtnodel .my domain. com/system 



The above example assumes that SSH connectivity between the management system 
and virtnodel.mydomain.com has already been configured, and uses SSH keys for 
authentication. SSH keys are needed because libvirt sends the password prompt to another 



process. For details on configuring SSH see Section 1, "OpenSSH Server" [p. 80] 

1.6. Virtual Machine Viewer 

The virt-viewer application allows you to connect to a virtual machine's console, virt- viewer does 
require a Graphical User Interface (GUI) to interface with the virtual machine. 

To install virt-viewer from a terminal enter: 
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sudo apt-get Install virt-viewer 

Once a virtual machine is installed and running you can connect to the virtual machine's console by 
using: 

virt-viewer -c qemu : ///system web_devel 

Similar to virt-manager, virt-viewer can connect to a remote host using SSH with key authentication, 
as well: 

virt-viewer -c qemu+ssh: //virtnodel .mydomain. com/system web_devel 

Be sure to replace web_devel with the appropriate virtual machine name. 

If configured to use a bridged network interface you can also setup SSH access to the virtual machine. 

1.7. Resources 

• See the KVM 2 home page for more details. 

• For more information on libvirt see the libvirt home page 3 

• The Virtual Machine Manager 4 site has more information on virt-manager development. 

• Also, stop by the #ubuntu-virt IRC channel on freenode 5 to discuss virtualization technology in 
Ubuntu. 

• Another good resource is the Ubuntu Wiki KVM 6 page. 

• For information on Xen, including using Xen with libvirt, please see the Ubuntu Wiki Xen page. 



http://www.linux-kvm.org/ 
http://libvirt.org/ 

http ://virt-manager .et .redhat .com/ 
http://freenode.net/ 

https://help.ubuntu.com/community/KVM 
https://help.ubuntu.com/community/Xen 
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2. Cloud images and uvtool 

2.1. Introduction 

With Ubuntu being one of the most used operating systems on most of the cloud platforms, the 
availability of stable and secure cloud images has become very important. As of 12.04 the utilization 
of cloud images outside of a cloud infrastructure has been improved. It is now possible to use those 
images to create a virtual machine without the need of a complete installation. 

2.2. Creating virtual machines using uvtool 

Starting with 14.04 LTS, a tool called uvtool greatly facilitates the task of generating virtual machines 
(VM) using the cloud images, uvtool provides a simple mechanism to to synchronize cloud-images 
locally and use them to create new VMs in minutes. 

2.2.1 . Uvtool packages 

The following packages and their dependancies will be required in order to use uvtool: 

• uvtool 

• uvtool-libvirt 

Installation of uvtool is done the same as for any other application by using apt-get: 
$ apt-get -y install uvtool 

This will install uvtool's main commands: 

• uvt-simplestreams-libvirt 

• uvt-kvm 

2.2.2. Get the Ubuntu Cloud Image with uvt-simplestreams-libvirt 

This is one of the major simplifications that uvtool brings. It is aware of where to find the cloud 
images so only one command is required to get a new cloud image. For instance, if you want to 
synchronize all cloud images for the amd64 architecture, the uvtool command would be: 

$ uvt-simplestreams-libvirt sync arch=amd64 

After an amount of time required to download all the images from the internet, you will have a 
complete set of cloud images stored locally. To see what has been downloaded use the following 
command: 

$ uvt-simplestreams-libvirt query 

release=oneiric arch=amd64 label=release (20130509) 
release=precise arch=amd64 label=release (20140227) 
release=quantal arch=amd64 label=release (20140302) 
release=saucy arch=amd64 label=release (20140226) 
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release=trusty arch=amd64 label=betal (20140226.1) 

In the case where you want to synchronize only one specific cloud-image, you need to use the 
release^ and arch= filters to identify which image needs to be synchronized. 

$ uvt-simplestreams-libvirt sync release=precise arch=amd64 

2.2.3. Create the VM using uvt-kvm 

In order to be able to connect to the virtual machine once it has been created, it is necessary to have 
a valid SSH key available for the ubuntu user. If your environment does not have a ssh key, you can 
easily create one using the following command: 

$ ssh-keygen 

Generating public/private rsa key pair. 

Enter file in which to save the key ( /home/ubuntu/ . ssh/id_rsa) : 
Enter passphrase (empty for no passphrase) : 
Enter same passphrase again: 

Your identification has been saved in /home/ubuntu/ . ssh/id_rsa . 
Your public key has been saved in /home/ubuntu/ . ssh/id_rsa . pub . 
The key fingerprint is: 

4d:ba:5d:57 :c9 :49 :ef :b5 :ab: 71 : 14 :56 : 6e:2b:ad: 9b ubuntu@TrustyS 
The key 1 s randomart image is : 
+--[ RSA 2048] + 

! ° • = I 

i m * * I 

I + ° += I 

i o . . + . | 

i . . o o I 

I * j 

I E I 
+ + 

The creation of a new virtual machine using uvtool is easy. In its simplest form, you only need to do: 
$ uvt-kvm create firsttest 

This will create a VM named firsttest using the current LTS cloud image available locally. If you 
want to specify a release to be used to create the VM, you need to use the release= filter 

$ uvt-kvm create secondtest release=trusty 

The uvt-kvm wait {name} can be used to wait until the creation of the VM has completed 
$ uvt-kvm wait secondttest — insecure 

Warning: secure wait for boot-finished not yet implemented; use — insecure. 

2.2.4. Connect to the running VM 

Once the virtual machine creation is completed, you can connect to it using ssh: 
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$ uvt-kvm ssh secondtest — insecure 

For the time being, the —insecure is required so you should be using this mechanism to connect to 
your VM only if you completely trust your network infrastructure 

You can also connect to your VM using a regular ssh session using the IP address of the VM. The 
address can be queried using the following command: 

$ uvt-kvm ip secondtest 
192.168.123.242 

$ ssh -i -/ . ssh/id_rsa ubuntu@ 192 . 168 . 123 . 242 

The authenticity of host '192.168.123.242 (192.168.123.242)' can't be established. 
ECDSA key fingerprint is 3a : 12 : 08 : 37 : 79 : 24 : 2f : 58 : aa : 62 : d3 : 9d: cO : 99 : 66 : 8a . 
Are you sure you want to continue connecting (yes/no)? yes 

Warning: Permanently added '192.168.123.242' (ECDSA) to the list of known hosts. 
Welcome to Ubuntu Trusty Tahr (development branch) (GNU/Linux 3 . 13 . 0-12-generic x86_64) 

* Documentation: https://help.ubuntu.com/ 

System information disabled due to load higher than 1 . 0 

Get cloud support with Ubuntu Advantage Cloud Guest: 
http: //www. ubuntu . com/business /services /cloud 

0 packages can be updated. 

0 updates are security updates. 

Last login: Fri Mar 21 13:25:56 2014 from 192.168.123.1 

2.2.5. Get the list of running VMs 

You can get the list of VM running on your system with this command: 

$ uvt-kvm list 
secondtest 

2.2.6. Destroy your VM 

Once you are done with your VM, you can proceed to destroy it with: 
$ uvt-kvm destroy secondtest 

2.2.7. More uvt-kvm options 

The following options can be used to change some of the characteristics of the virtual memory that 
you are creating 

• —memory : Amount of RAM in megabytes. Default: 512 

• -disk : Size of the OS disk in gigabytes. Default: 8 
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• -cpu : Number of CPU cores. Default: 1 

Some other parameters will have an impact on the cloud-init configuration 

• —password password : Allow login to the VM using the ubuntu account and this provided password 

• —run-script-one script_file : Run script_file as root on the VM the first time it is booted, but never 
again. 

• —packages package_list : Install the comma-separated packages specified in package_list on first 
boot. 

A complete description of all available modifiers is available in the manpage of uvt-kvm 

2.3. Resources 

If you are interested in learning more, have questions or suggestions, please contact the Ubuntu Server 
Team at: 

• IRC: #ubuntu-server on freenode 

• Mailing list: ubuntu-server at lists .ubuntu. con? 



https://lists.ubuntu.com/mailman/listinfo/ubuntu-server 
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3. Ubuntu Cloud 

Cloud computing is a computing model that allows vast pools of resources to be allocated on-demand. 
These resources such as storage, computing power, network and software are abstracted and delivered 
as a service over the Internet anywhere, anytime. These services are billed per time consumed 
similar to the ones used by public services such as electricity, water and telephony. Ubuntu Cloud 
Infrastructure uses OpenStack open source software to help build highly scalable, cloud computing 
for both public and private clouds. 

3.1. Installation and Configuration 

Due to the current high rate of development of this complex technology we refer the reader to 
upstream documentation 9 for all matters concerning installation and configuration. 

3.2. Support and Troubleshooting 

Community Support 

• OpenStack Mailing list 10 

• The OpenStack Wiki search 11 

• Launchpad bugs area 12 

• Join the IRC channel #openstack on freenode. 

3.3. Resources 

• Cloud Computing - Service models 13 

• OpenStack Compute 14 

• OpenStack Image Service 15 

• OpenStack Object Storage Administration Guide 16 

• Installing OpenStack Object Storage on Ubuntu 11 

• http://cloudglossary.com/ 



http://docs.openstack.org/havana/install-guide/install/apt/content/ 
" https ://launchpad.net/~openstack 
1 http://wiki.openstack.org 
https://bugs.launchpad.net/nova 

http://en.wikipedia.Org/wiki/Cloud_computing#Service_Models 
* http://www.openstack.org/software/openstack-compute/ 

' http://docs.openstack.org/diablo/openstack-compute/starter/content/GlanceMS-d2s21.html 

6 http://docs.openstack.org/trunk/openstack-object-storage/admin/content/index.html 

7 http://docs.openstack.org/trunk/openstack-object-storage/admin/content/installing-openstack-object-storage-on-ubuntu.html 
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4. LXC 

Containers are a lightweight virtualization technology. They are more akin to an enhanced chroot than 
to full virtualization like Qemu or VMware, both because they do not emulate hardware and because 
containers share the same operating system as the host. Therefore containers are better compared to 
Solaris zones or BSD jails. Linux-vserver and OpenVZ are two pre-existing, independently developed 
implementations of containers-like functionality for Linux. In fact, containers came about as a result 
of the work to upstream the vserver and OpenVZ functionality. 

There are two user-space implementations of containers, each exploiting the same kernel features. 
Libvirt allows the use of containers through the LXC driver by connecting to 'lxc :///'. This can be very 
convenient as it supports the same usage as its other drivers. The other implementation, called simply 
LXC, is not compatible with libvirt, but is more flexible with more userspace tools. It is possible to 
switch between the two, though there are peculiarities which can cause confusion. 

In this document we will mainly describe the lxc package. Use of libvirt-lxc is not generally 
recommended due to a lack of Apparmor protection for libvirt-lxc containers. 

In this document, a container name will be shown as CN, CI , or C2. 

4.1. Installation 

The lxc package can be installed using 



sudo apt-get install lxc 



This will pull in the required and recommended dependencies, as well as set up a network bridge for 
containers to use. If you wish to use unprivileged containers, you will need to ensure that users have 
sufficient allocated subuids and subgids, and will likely want to allow users to connect containers to a 
bridge (see Section 4.2.3, "Basic unprivileged usage" [p. 325]). 

4.2. Basic usage 

LXC can be used in two distinct ways - privileged, by running the lxc commands as the root user; 
or unprivileged, by running the lxc commands as a non-root user. (The starting of unprivileged 
containers by the root user is possible, but not described here.) Unprivileged containers are more 
limited, for instance being unable to create device nodes or mount block-backed filesy stems. However 
they are less dangerous to the host, as the root userid in the container is mapped to a non-root userid 
on the host. 

4.2.1 . Basic privileged usage 

To create a privileged container, you can simply to 
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sudo lxc-create — template download — name ul 

or, abbreviated 

sudo lxc-create -t download -n ul 

This will interactively ask for a container root filesystem type to download - in particular the 
distribution, release, and architecture. To create the container non-interactively, you can specify these 
values on the command line: 

sudo lxc-create -t download -n ul — — dlst ubuntu — release trusty — arch amd64 

or 

sudo lxc-create -t download -n ul — -d ubuntu -r trusty -a amd64 

You can now use lxc-ls to list containers, lxc-info to obtain detailed container information, lxc-start 
to start and lxc-stop to stop the container, lxc-attach and lxc-console allow you to enter a container, if 
ssh is not an option, lxc-destroy removes the container, including its rootfs. See the manual pages for 
more information on each command. An example session might look like: 



sudo 


lxc 


-Is — fancy 


sudo 


lxc 


-start --name ul --daemon 


sudo 


lxc 


-info --name ul 


sudo 


lxc 


-stop --name ul 


sudo 


lxc 


-destroy — name ul 



4.2.2. User namespaces 

Unprivileged containers allow users to create and administer containers without having any root 
privilege. The feature underpinning this is called user namespaces. User namespaces are hierarchical, 
with privileged tasks in a parent namespace being able to map its ids into child namespaces. By 
default every task on the host runs in the initial user namespace, where the full range of ids is mapped 
onto the full range. This can be seen by looking at /proc/self/uid_map and /proc/self/gid_map, which 
both will show "0 0 4294967295" when read from the initial user namespace. As of Ubuntu 14.04, 
when new users are created they are by default offered a range of userids. The list of assigned ids 
can be seen in the files /etc/subuid and /etc/subgid See their respective manpages for more 
information. Subuids and subgids are by convention started at id 100000 to avoid conflicting with 
system users. 

If a user was created on an earlier release, it can be granted a range of ids using usermod, as follows: 



324 



Virtualization 



sudo usermod -v 100000-200000 -w 100000-200000 userl 

The programs newuidmap and newgidmap are setuid-root programs in the uidmap package, which 
are used internally by lxc to map subuids and subgids from the host into the unprivileged container. 
They ensure that the user only maps ids which are authorized by the host configuration. 

4.2.3. Basic unprivileged usage 

To create unprivileged containers, a few first steps are needed. You will need to create a default 
container configuration file, specifying your desired id mappings and network setup, as well as 
configure the host to allow the unprivileged user to hook into the host network. The example below 
assumes that your mapped user and group id ranges are 100000-165536. 

mkdir -p -/ . conf ig/lxc 

echo "lxc.id_map = u 0 100000 65536" > -/. conf ig/lxc/def ault . conf 
echo "lxc.id_map = g 0 100000 65536" » -/. conf ig/lxc/def ault . conf 
echo "lxc. network. type = veth" » -/. conf ig/lxc/def ault . conf 
echo " lxc . network . link = lxcbrO" » -/. conf ig/lxc/def ault . conf 
echo "$USER veth lxcbrO 2" | sudo tee -a /etc/lxc/lxc-usernet 

After this, you can create unprivileged containers the same way as privileged ones, simply without 
using sudo. 

lxc-create -t download -n ul — -d ubuntu -r trusty -a amd64 
lxc-start -n ul -d 
lxc-attach -n ul 
lxc-stop -n ul 
lxc-destroy -n ul 

4.2.4. Nesting 

In order to run containers inside containers - referred to as nested containers - two lines must be 
present in the parent container configuration file: 

lxc .mount . auto = cgroup 

lxc . aa_prof ile = lxc-container-def ault-with-nesting 

The first will cause the cgroup manager socket to be bound into the container, so that lxc inside the 
container is able to administer cgroups for its nested containers. The second causes the container to 
run in a looser Apparmor policy which allows the container to do the mounting required for starting 
containers. Note that this policy, when used with a privileged container, is much less safe than the 
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regular policy or an unprivileged container. See Section 4.9, "Apparmor" [p. 329] for more 
information. 

4.3. Global configuration 

The following configuration files are consulted by LXC. For privileged use, they are found under / 
etc /lxc, while for unprivileged use they are under -/ .conf ig/lxc. 

• lxc . conf may optionally specify alternate values for several lxc settings, including the lxcpath, the 
default configuration, cgroups to use, a cgroup creation pattern, and storage backend settings for 
lvm and zfs. 

• default . conf specifies configuration which every newly created container should contain. This 
usually contains at least a network section, and, for unprivileged users, an id mapping section 

• lxc-usernet . conf specifies how unprivileged users may connect their containers to the host- 
owned network. 

lxc .conf and default .conf are exist both under /etc/lxc and $HOME/ .conf ig/lxc, while lxc- 
usernet. conf is only host-wide. 

By default, containers are located under /var/lib/lxc for the root user, and $HOME/.local/share/lxc 
otherwise. The location can be specified for all lxc commands using the "-Pl-lxcpath" argument. 

4.4. Networking 

By default LXC creates a private network namespace for each container, which includes a layer 2 
networking stack. Containers usually connect to the outside world by either having a physical NIC 
or a veth tunnel endpoint passed into the container. LXC creates a NATed bridge, lxcbrO, at host 
startup. Containers created using the default configuration will have one veth NIC with the remote 
end plugged into the lxcbrO bridge. A NIC can only exist in one namespace at a time, so a physical 
NIC passed into the container is not usable on the host. 

It is possible to create a container without a private network namespace. In this case, the container 
will have access to the host networking like any other application. Note that this is particularly 
dangerous if the container is running a distribution with upstart, like Ubuntu, since programs which 
talk to init, like shutdown, will talk over the abstract Unix domain socket to the host's upstart, and 
shut down the host. 

To give containers on lxcbrO a persistent ip address based on domain name, you can write entries to / 
etc/lxc/dnsmasq.conf like: 

dhcp-host=lxcmail, 10.0.3. 100 
dhcp-host=ttrss, 10 . 0.3.101 

If it is desirable for the container to be publicly accessible, there are a few ways to go about it. One is 
to use iptables to forward host ports to the container, for instance 
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iptables -t nat -A PREROUTING -p tcp -i ethO — dport 587 -j DNAT \ 
— to-destination 10.0.3.100:587 

Another is to bridge the host's network interfaces (see the Ubuntu Server Guide's Network 
Configuration chapter, Section 1.4, "Bridging" [p. 40]). Then, specify the host's bridge in the 
container configuration file in place of lxcbrO, for instance 

lxc . network . type = veth 
lxc . network . link = brO 

Finally, you can ask LXC to use macvlan for the container's NIC. Note that this has limitations and 
depending on configuration may not allow the container to talk to the host itself. Therefore the other 
two options are preferred and more commonly used. 

There are several ways to determine the ip address for a container. First, you can use lxc-ls —fancy 
which will print the ip addresses for all running containers, or lxc-info -i -H -n CI which will print 
Cl's ip address. If dnsmasq is installed on the host, you can also add an entry to /etc/dnsmasq.conf 
as follows 

server=/lxc/10 . 0.3.1 

after which dnsmasq will resolve CI .lxc locally, so that you can do: 

ping CI 
ssh CI 

For more information, see the lxc.conf manpage as well as the example network configurations under 
/usr/ share/doc /lxc /examples/. 

4.5. LXC startup 

LXC does not have a long-running daemon. However it does have three upstart jobs. 

• /etc/init/ixc-net.conf : is an optional job which only runs if /etc/def auit/ixc-net specifies 
US E_LXC_B RIDGE (true by default). It sets up a NATed bridge for containers to use. 

• /etc/init/lxc.conf loads the lxc apparmor profiles and optionally starts any autostart containers. 
The autostart containers will be ignored if LXC_AUTO (true by default) is set to true in /etc/ 
def ault/lxc. See the lxc-autostart manual page for more information on autostarted containers. 

• /etc/init/ixc-instance . conf : is used by /etc/init/ixc . conf to autostart a container. 

4.6. Backing Stores 

LXC supports several backing stores for container root filesy stems. The default is a simple directory 
backing store, because it requires no prior host customization, so long as the underlying filesy stem 
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is large enough. It also requires no root privilege to create the backing store, so that it is seamless for 
unprivileged use. The rootfs for a privileged directory backed container is located (by default) under 
/var/iib/ixc/ci/rootfs, while the rootfs for an unprivileged container is under -/ .local/share/ 
lxc/ci/rootf s. If a custom lxcpath is specified in lxc.system.com, then the container rootfs will be 
under $lxcpath/Cl/rootf s. 

A snapshot clone C2 of a directory backed container CI becomes an overlayfs backed container, with 
a rootfs called overlayfs : /var/lib/lxc/Cl/rootf s : /var/lib/lxc/C2/deltaO. Other backing Store 
types include loop, btrfs, LVM and zfs. 

A btrfs backed container mostly looks like a directory backed container, with its root filesystem in 
the same location. However, the root filesystem comprises a subvolume, so that a snapshot clone is 
created using a subvolume snapshot. 

The root filesystem for an LVM backed container can be any separate LV. The default VG name can 
be specified in lxc.conf. The filesystem type and size are configurable per-container using lxc-create. 

The rootfs for a zfs backed container is a separate zfs filesystem, mounted under the traditional /var/ 
lib/ixc/ci/rootf s location. The zfsroot can be specified at lxc-create, and a default can be specified 
in lxc.system.conf. 

More information on creating containers with the various backing stores can be found in the lxc-create 
manual page. 

4.7. Templates 

Creating a container generally involves creating a root filesystem for the container, lxc-create 
delegates this work to templates, which are generally per-distribution. The lxc templates shipped with 
lxc can be found under /usr/share/lxc/templates, and include templates to create Ubuntu, Debian, 
Fedora, Oracle, centos, and gentoo containers among others. 

Creating distribution images in most cases requires the ability to create device nodes, often requires 
tools which are not available in other distributions, and usually is quite time-consuming. Therefore lxc 
comes with a special download template, which downloads pre-built container images from a central 
lxc server. The most important use case is to allow simple creation of unprivileged containers by non- 
root users, who could not for instance easily run the debootstrap command. 

When running lxc-create, all options which come after — are passed to the template. In the following 
command, -name, -template and —bdev are passed to lxc-create, while -release is passed to the 
template: 

lxc-create — template ubuntu — name cl — bdev loop — — release trusty 
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You can obtain help for the options supported by any particular container by passing -help and the 
template name to lxc-create. For instance, for help with the download template, 

lxc-create — template download — help 

4.8. Autostart 

LXC supports marking containers to be started at system boot. Prior to Ubuntu 14.04, this was done 
using symbolic links under the directory /etc/lxc/auto. Starting with Ubuntu 14.04, it is done 
through the container configuration files. An entry 

lxc. start. auto = 1 
lxc. start. delay = 5 

would mean that the container should be started at boot, and the system should wait 5 seconds before 
starting the next container. LXC also supports ordering and grouping of containers, as well as reboot 
and shutdown by autostart groups. See the manual pages for lxc-autostart and lxc .container .conf for 
more information. 

4.9. Apparmor 

LXC ships with a default Apparmor profile intended to protect the host from accidental misuses of 
privilege inside the container. For instance, the container will not be able to write to /proc/sysrq- 
trigger or to most /sys files. 

The usr .bin.lxc-start profile is entered by running lxc-start. This profile mainly prevents lxc- 
start from mounting new filesystems outside of the container's root filesystem. Before executing the 
container's init, LXC requests a switch to the container's profile. By default, this profile is the lxc- 
container-def ault policy which is defined in /etc/apparmor . d/lxc/lxc-def ault. This profile 
prevents the container from accessing many dangerous paths, and from mounting most filesystems. 

Programs in a container cannot be further confined - for instance, MySQL runs under the container 
profile (protecting the host) but will not be able to enter the MySQL profile (to protect the container). 

lxc-execute does not enter an Apparmor profile, but the container it spawns will be confined. 

4.9.1. Customizing container policies 

If you find that lxc-start is failing due to a legitimate access which is being denied by its Apparmor 
policy, you can disable the lxc-start profile by doing: 

sudo apparmor_parser -R /etc/apparmor . d/usr .bin . lxc-start 

sudo In -s /etc/apparmor .d/usr. bin. lxc-start /etc/apparmor . d/disabled/ 
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This will make lxc-start run unconfined, but continue to confine the container itself. If you also wish 
to disable confinement of the container, then in addition to disabling the usr. bin. lxc-start profile, 
you must add: 

lxc . aa_prof ile = unconfined 
to the container's configuration file. 

LXC ships with a few alternate policies for containers. If you wish to run containers inside containers 
(nesting), then you can use the lxc-container-default-with-nesting profile by adding the following line 
to the container configuration file 

lxc . aa_prof ile = lxc-container-def ault-with-nesting 

If you wish to use libvirt inside containers, then you will need to edit that policy (which is defined in / 
etc/apparmor .d/lxc/lxc-def ault-with-nesting) to uncomment the following line 

mount f stype=cgroup -> /sys/f s/cgroup/** , 

and re-load the policy. 

Note that the nesting policy with privileged containers is far less safe than the default policy, as 
it allows containers to re-mount /sys and /proc in nonstandard locations, bypassing apparmor 
protections. Unprivileged containers do not have this drawback since the container root cannot write 
to root-owned proc and sys files. 

Another profile shipped with lxc allows containers to mount block filesystem types like ext4. This can 
be useful in some cases like maas provisioning, but is deemed generally unsafe since the superblock 
handlers in the kernel have not been audited for safe handling of untrusted input. 

If you need to run a container in a custom profile, you can create a new profile under /etc/ 
apparmor .d/ lxc/. Its name must start with lxc- in order for lxc-start to be allowed to transition 
to that profile. The lxc-default profile includes the re-usable abstractions file /etc/apparmor .d/ 
abstractions/ixc/container-base. An easy way to start a new profile therefore is to do the same, 
then add extra permissions at the bottom of your policy. 

After creating the policy, load it using: 

sudo apparmor_parser -r /etc/apparmor . d/lxc-containers 

The profile will automatically be loaded after a reboot, because it is sourced by the file /etc/ 
apparmor .d/lxc-containers. Finally, to make container cn use this new lxc-CN-prof ile, add the 
following line to its configuration file: 
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lxc . aa_prof ile = lxc-CN-prof ile 

4.10. Control Groups 

Control groups (cgroups) are a kernel feature providing hierarchical task grouping and per-cgroup 
resource accounting and limits. They are used in containers to limit block and character device access 
and to freeze (suspend) containers. They can be further used to limit memory use and block i/o, 
guarantee minimum cpu shares, and to lock containers to specific cpus. 

By default, a privileged container CN will be assigned a cgroup called /1xc/cn. In the case of name 
conflicts (which can occur when using custom lxcpaths) a suffix "-n" , where n is an integer starting at 
0, will be appended to the cgroup name. 

By default, a privileged container CN will be assigned a cgroup called cn under the cgroup of the task 
which started the container, for instance /usr/iooo .user/i .session/CN. The container root will 
be given group ownership of the directory (but not all files) so that it is allowed to create new child 
cgroups. 

As of Ubuntu 14.04, LXC uses the cgroup manager (cgmanager) to administer cgroups. The cgroup 
manager receives D-Bus requests over the Unix socket /sys/f s/cgroup/cgmanager/sock. To 
fascilitate safe nested containers, the line 

lxc. mount. auto = cgroup 

can be added to the container configuration causing the /sys/f s/cgroup/cgmanager directory to be 
bind-mounted into the container. The container in turn should start the cgroup management proxy 
(done by default if the cgmanager package is installed in the container) which will move the / sys/ f s/ 
cgroup/cgmanager directory to /sys/f s/cgroup/cgmanager . lower, then Start listening for requests 
to proxy on its own socket /sys/f s/cgroup/cgmanager/sock. The host cgmanager will ensure that 
nested containers cannot escape their assigned cgroups or make requests for which they are not 
authorized. 

4.11. Cloning 

For rapid provisioning, you may wish to customize a canonical container according to your needs and 
then make multiple copies of it. This can be done with the lxc-clone program. 

Clones are either snapshots or copies of another container. A copy is a new container copied from 
the original, and takes as much space on the host as the original. A snapshot exploits the underlying 
backing store's snapshotting ability to make a copy-on- write container referencing the first. Snapshots 
can be created from btrfs, LVM, zfs, and directory backed containers. Each backing store has its 
own peculiarities - for instance, LVM containers which are not thinpool-provisioned cannot support 
snapshots of snapshots; zfs containers with snapshots cannot be removed until all snapshots are 
released; LVM containers must be more carefully planned as the underlying filesystem may not 
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support growing; btrfs does not suffer any of these shortcomings, but suffers from reduced fsync 
performance causing dpkg and apt-get to be slower. 

Snapshots of directory -packed containers are created using the overlay filesystem. For instance, 
a privileged directory-backed container CI will have its root filesystem under /var/lib/lxc/ci/ 
rootf s. A snapshot clone of CI called C2 will be started with Cl's rootfs mounted readonly under / 
var/iib/ixc/c2/delta0. Importantly, in this case CI should not be allowed to run or be removed 
while C2 is running. It is advised instead to consider CI a canonical base container, and to only use 
its snapshots. 

Given an existing container called CI , a copy can be created using: 

sudo lxc-clone -o CI -n C2 

A snapshot can be created using 

sudo lxc-clone -s -o CI -n C2 

See the lxc-clone manpage for more information. 
4.11.1. Snapshots 

To more easily support the use of snapshot clones for iterative container development, LXC supports 
snapshots. When working on a container CI , before making a potentially dangerous or hard-to-revert 
change, you can create a snapshot 

sudo lxc-snapshot -n CI 

which is a snapshot-clone called 'snapO' under /var/lib/lxcsnaps or $HOME/.local/share/lxcsnaps. The 
next snapshot will be called 'snapl', etc. Existing snapshots can be listed using lxc-snapshot -L -n 
CI, and a snapshot can be restored - erasing the current CI container - using lxc-snapshot -r snapl - 
n CI. After the restore command, the snapl snapshot continues to exist, and the previous CI is erased 
and replaced with the snapl snapshot. 

Snapshots are supported for btrfs, lvm, zfs, and overlayfs containers. If lxc-snapshot is called on a 
directory-backed container, an error will be logged and the snapshot will be created as a copy-clone. 
The reason for this is that if the user creates an overlayfs snapshot of a directory-backed container 
and then makes changes to the directory-backed container, then the original container changes will be 
partially reflected in the snapshot. If snapshots of a directory backed container CI are desired, then an 
overlayfs clone of CI should be created, CI should not be touched again, and the overlayfs clone can 
be edited and snapshotted at will, as such 



332 



Virtualization 



lxc-clone -s -o CI -n C2 

lxc-start -n C2 -d # make some changes 

lxc-stop -n C2 

lxc-snapshot -n C2 

lxc-start -n C2 # etc 



4.1 1 .2. Ephemeral Containers 

While snapshots are useful for longer-term incremental development of images, ephemeral containers 
utilize snapshots for quick, single-use throwaway containers. Given a base container CI , you can start 
an ephemeral container using 



lxc-start-ephemeral -o CI 



The container begins as a snapshot of C 1 . Instructions for logging into the container will be printed to 
the console. After shutdown, the ephemeral container will be destroyed. See the lxc-start-ephemeral 
manual page for more options. 

4.12. Lifecycle management hooks 

Beginning with Ubuntu 12.10, it is possible to define hooks to be executed at specific points in a 
container's lifetime: 

• Pre-start hooks are run in the host's namespace before the container ttys, consoles, or mounts are 
up. If any mounts are done in this hook, they should be cleaned up in the post-stop hook. 

• Pre-mount hooks are run in the container's namespaces, but before the root filesystem has been 
mounted. Mounts done in this hook will be automatically cleaned up when the container shuts 
down. 

• Mount hooks are run after the container filesy stems have been mounted, but before the container 
has called pivot_root to change its root filesystem. 

• Start hooks are run immediately before executing the container's init. Since these are executed 
after pivoting into the container's filesystem, the command to be executed must be copied into the 
container's filesystem. 

• Post- stop hooks are executed after the container has been shut down. 

If any hook returns an error, the container's run will be aborted. Any post-stop hook will still be 
executed. Any output generated by the script will be logged at the debug priority. 

Please see the lxc .container .conf manual page for the configuration file format with which to specify 
hooks. Some sample hooks are shipped with the lxc package to serve as an example of how to write 
and use such hooks. 
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4.13. Consoles 

Containers have a configurable number of consoles. One always exists on the container's /dev/ 
console. This is shown on the terminal from which you ran lxc-start, unless the -d option is 
specified. The output on /dev/console can be redirected to a file using the -c console-file option to 
lxc-start. The number of extra consoles is specified by the lxc.tty variable, and is usually set to 4. 
Those consoles are shown on /dev/ttyN (for 1 <= N <= 4). To log into console 3 from the host, use 

sudo lxc-console -n container -t 3 

or if the -t N option is not specified, an unused console will be automatically chosen. To exit the 
console, use the escape sequence Ctrl-a q. Note that the escape sequence does not work in the console 
resulting from lxc-start without the -d option. 

Each container console is actually a Unix98 pty in the host's (not the guest's) pty mount, bind- 
mounted over the guest's /dev/ttyN and /dev/console. Therefore, if the guest unmounts those or 
otherwise tries to access the actual character device 4:N, it will not be serving getty to the LXC 
consoles. (With the default settings, the container will not be able to access that character device and 
getty will therefore fail.) This can easily happen when a boot script blindly mounts a new /dev. 

4.14. Troubleshooting 

4.14.1. Logging 

If something goes wrong when starting a container, the first step should be to get full logging from 
LXC: 

sudo lxc-start -n CI -1 trace -o debug. out 

This will cause lxc to log at the most verbose level, trace, and to output log information to a file 
called 'debug .out'. If the file debug. out already exists, the new log information will be appended. 

4.14.2. Monitoring container status 

Two commands are available to monitor container state changes, lxc-monitor monitors one or more 
containers for any state changes. It takes a container name as usual with the -n option, but in this case 
the container name can be a posix regular expression to allow monitoring desirable sets of containers, 
lxc-monitor continues running as it prints container changes, lxc- wait waits for a specific state 
change and then exits. For instance, 

sudo lxc-monitor -n cont[0-5]* 
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would print all state changes to any containers matching the listed regular expression, whereas 
sudo lxc-wait -n contl -s ' STOPPED | FROZEN ' 

will wait until container contl enters state STOPPED or state FROZEN and then exit. 

4.14.3. Attach 

As of Ubuntu 14.04, it is possible to attach to a container's namespaces. The simplest case is to simply 
do 

sudo lxc-attach -n CI 

which will start a shell attached to CPs namespaces, or, effectively inside the container. The attach 
functionality is very flexible, allowing attaching to a subset of the container's namespaces and security 
context. See the manual page for more information. 

4.14.4. Container init verbosity 

If LXC completes the container startup, but the container init fails to complete (for instance, no login 
prompt is shown), it can be useful to request additional verbosity from the init process. For an upstart 
container, this might be: 



sudo lxc-start -n CI /sbin/init loglevel=debug 



You can also start an entirely different program in place of init, for instance 



sudo lxc-start -n CI 
sudo lxc-start -n CI 
sudo lxc-start -n CI 



/bin/bash 
/bin/sleep 100 
/bin/cat /proc/l/status 



4.15. LXC API 

Most of the LXC functionality can now be accessed through an API exported by liblxc for which 
bindings are available in several languages, including Python, lua, ruby, and go. 

Below is an example using the python bindings (which are available in the python3-lxc package) 
which creates and starts a container, then waits until it has been shut down: 
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# sudo python3 

Python 3.2.3 (default, Aug 28 2012, 08:26:03) 
[GCC 4.7.1 20120814 (prerelease)] on linux2 

Type "help", "copyright", "credits" or "license" for more information. 
»> import lxc 

main :1: Warning: The python-lxc API isn't yet stable and may change at any p 

oint in the future. 

»> c=lxc. Container ( "CI" ) 

»> c. create ( "ubuntu" ) 

True 

»> c . start ( ) 
True 

»> c .wait ( "STOPPED" ) 
True 

4.16. Security 

A namespace maps ids to resources. By not providing a container any id with which to reference a 
resource, the resource can be protected. This is the basis of some of the security afforded to container 
users. For instance, IPC namespaces are completely isolated. Other namespaces, however, have 
various leaks which allow privilege to be inappropriately exerted from a container into another 
container or to the host. 

By default, LXC containers are started under a Apparmor policy to restrict some actions. The details 
of App Armor integration with lxc are in section Section 4.9, "Apparmor" [p. 329]. Unprivileged 
containers go further by mapping root in the container to an unprivileged host userid. This prevents 
access to /proc and /sys files representing host resources, as well as any other files owned by root on 
the host. 

4.16.1. Exploitable system calls 

It is a core container feature that containers share a kernel with the host. Therefore if the kernel 
contains any exploitable system calls the container can exploit these as well. Once the container 
controls the kernel it can fully control any resource known to the host. 

Since Ubuntu 12.10 (Quantal) a container can also be constrained by a seccomp filter. Seccomp is 
a new kernel feature which filters the system calls which may be used by a task and its children. 
While improved and simplified policy management is expected in the near future, the current policy 
consists of a simple whitelist of system call numbers. The policy file begins with a version number 
(which must be 1) on the first line and a policy type (which must be 'whitelist') on the second line. It is 
followed by a list of numbers, one per line. 

In general to run a full distribution container a large number of system calls will be needed. However 
for application containers it may be possible to reduce the number of available system calls to only 
a few. Even for system containers running a full distribution security gains may be had, for instance 
by removing the 32-bit compatibility system calls in a 64-bit container. See the lxc .container .conf 
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manual page for details of how to configure a container to use seccomp. By default, no seccomp 
policy is loaded. 

4.17. Resources 

• The DeveloperWorks article LXC: Linux container tools l& was an early introduction to the use of 
containers. 

• The Secure Containers Cookbook 19 demonstrated the use of security modules to make containers 
more secure. 

• Manual pages referenced above can be found at: 

20 

capabilities 

21 

lxc. conf 

• The upstream LXC project is hosted at linuxcontainers.org 22 . 

• LXC security issues are listed and discussed at the LXC Security wiki page 23 

• For more on namespaces in Linux, see: S. Bhattiprolu, E. W. Biederman, S. E. Hallyn, and D. 
Lezcano. Virtual Servers and Check- point/Restart in Mainstream Linux. SIGOPS Operating 
Systems Review, 42(5), 2008. 



https://www.ibm.com/developerworks/linux/library/l-lxc-containers/ 

http ://www .ibm .com/developerworks/linux/library/l-lxc- security/index .html 

http://manpages.ubuntu.eom/manpages/en/man7/capabilities.7.html 

http://manpages.ubuntu.eom/manpages/en/man5/lxc.conf.5.html 

http://linuxcontainers.org 

http://wiki.ubuntu.com/LxcSecurity 
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Control groups (cgroups) are a kernel mechanism for grouping, tracking, and limiting the resource 
usage of tasks. The kernel -provided administration interface is through a virtual filesystem. Higher 
level cgroup administration tools have been developed, including libcgroup and lmctfy. Additionally, 
there is guidance at freedesktop.org for how applications can best cooperate using the cgroup 
filesystem interface (see Resources). 

As of Ubuntu 14.04, the cgroup manager (cgmanager) is available as another cgroup administion 
interface. It's goal is to respond to dbus requests from any user, allowing him to administer only those 
cgroups which have been delegated to him. 

Section 1, "Overview" [p. 339] will describe cgroups in more detail. Section 2, 
"Filesystem" [p. 340] will describe the long-standing cgroups filesystem interface. Section 4, 
"Manager" [p. 342] will describe the cgroup manager. 
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1. Overview 

Cgroups are the generalized feature for grouping tasks. The actual resource tracking and limits are 
implemented by subsystems. A hierarchy is a set of subsystems mounted together. For instance, if the 
memory and devices subsystems are mounted together under /sys/fs/cgroups/setl , then any task which 
is in "/child 1" will be subject to the corresponding limits of both subsystems. 

Each set of mounted subsystems consittutes a 'hierarchy'. With exceptions, cgroups which are children 
of "/childl" will be subject to all limits placed on "/childl", and their resource usage will be accounted 
to "/childl". 

The existing subsystems include: 

• cpusets: fascilitate assigning a set of CPUS and memory nodes to cgroups. Tasks in a cpuset cgroup 
may only be scheduled on CPUS assigned to that cpuset. 

• blkio : limits per-cgroup block io. 

• cpuacct : provides per-cgroup cpu usage accounting. 

• devices : controls the ability of tasks to create or use devices nodes using either a blacklist or 
whitelist. 

• freezer : provides a way to 'freeze' and 'thaw' whole cgroups. Tasks in the cgroup will not be 
scheduled while they are frozen. 

• hugetlb : fascilitates limiting hugetlb usage per cgroup. 

• memory : allows memory, kernel memory, and swap usage to be tracked and limited. 

• net_cls : provides an interface for tagging packets based on the sender cgroup. These tags can then 
be used by tc (traffic controller) to assign priorities. 

• net jprio : allows setting network traffic priority on a per-cgroup basis. 

• cpu : enables setting of scheduling preferences on per-cgroup basis. 

• perf_event : enables per-cpu mode to monitor only threads in certain cgroups. 

In addition, named cgroups can be created with no bound subsystems for the sake of process tracking. 
As an example, systemd does this to track services and user sessions. 
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2. Filesystem 

A hierarchy is created by mounting an instance of the cgroup filesystem with each of the desired 
subsystems listed as a mount option. For instance, 

mount -t cgroup -o devices , memory , freezer cgroup /cgroupl 

would instantiate a hierarchy with the devices and memory cgroups comounted. A child cgroup 
"childl" can be created using 'mkdir' 

mkdir /cgroupl/childl 

and tasks can be moved into the new child cgroup by writing their process ids into the 'tasks' or 
'cgroup .procs' file: 

sleep 100 

echo $! > /cgroupl /childl /cgroup. procs 

Other administration is done through files in the cgroup directories. For instance, to freeze all tasks in 
childl, 

echo FROZEN > /cgroupl/childl/f reezer . state 

A great deal of information about cgroups and its subsystems can be found under the cgroups 
documentation directory in the kernel source tree (see Resources). 
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3. Delegation 

Cgroup files and directories can be owned by non-root users, enabling delegation of cgroup 
administration. In general, the kernel enforces the hierarchical constraints on limits, so that for 
instance if devices cgroup /chiidi cannot access a disk drive, then /childi/child2 cannot give itself 
those rights. 

As of Ubuntu 14.04, users are automatically placed in a set of cgroups which they own, safely 
allowing them to contrain their own jobs using child cgroups. This feature is relied upon, for instance, 
for unprivileged container creation in lxc. 
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4. Manager 

The cgroup manager (cgmanager) provides a D-Bus service allowing programs and users to 
administer cgroups without needing direct knowledge of or access to the cgroup filesystem. For 
requests from tasks in the same namespaces as the manager, the manager can directly perform the 
needed security checks to ensure that requests are legitimate. For other requests - such as those from a 
task in a container - enhanced D-Bus requests must be made, where process-, user- and group-ids are 
passed as SCM_CREDENTIALS , so that the kernel maps the identifiers to their global host values. 

To fascilitate the use of simple D-Bus calls from all users, a 'cgroup manager proxy' (cgproxy) is 
automatically started when in a container. The proxy accepts standard D-Bus requests from tasks in 
the same namespaces as itself, and converts them to SCM-enhanced D-Bus requests which it passes 
on to the cgmanager. 

A simple example of creating a new cgroup in which to run a cpu-intensive compile would look like: 

cgm create cpuset buildl 

cgm movepid cpuset buildl $$ 

cgm setvalue cpuset buildl cpuset. cpus 1 

make 
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5. Resources 

• Manual pages referenced above can be found at: 
cgm 1 

cgconfig. conf 2 

cgmanager 3 

4 

cgproxy 

• The upstream cgmanager project is hosted at linuxcontainers.org 5 . 

• The upstream kernel documentation page on cgroups can be seen here 6 . 

• The freedesktop.org control group usage guidelines can be seen here 1 . 



http://manpages.ubuntu.com/manpages/en/man8/cgm.l.html 

http://manpages.ubuntu.eom/manpages/en/man5/cgconfig.conf.5.html 

http://manpages.ubuntu.eom/manpages/en/man8/cgmanager.8.html 

http://manpages.ubuntu.eom/manpages/en/man8/cgproxy.8.html 

http://cgmanager.linuxcontainers.org 

https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/cgroups 
http://www.freedesktop.org/wiki/Software/systemd/PaxControlGroups/ 
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l.DRBD 



Distributed Replicated Block Device (DRBD) mirrors block devices between multiple hosts. The 
replication is transparent to other applications on the host systems. Any block device hard disks, 
partitions, RAID devices, logical volumes, etc can be mirrored. 

To get started using drbd, first install the necessary packages. From a terminal enter: 



sudo apt-get install drbd8-utils 



| If you are using the virtual kernel as part of a virtual machine you will need to manually 
compile the drbd module. It may be easier to install the linux- server package inside the 
virtual machine. 



This section covers setting up a drbd to replicate a separate /srv partition, with an ext3 filesystem 
between two hosts. The partition size is not particularly relevant, but both partitions need to be the 
same size. 

1.1. Configuration 

The two hosts in this example will be called drbdOl and drbd02. They will need to have name 
resolution configured either through DNS or the /etc/hosts file. See Chapter 8, Domain Name 
Service (DNS) [p. 138] for details. 

• To configure drbd, on the first host edit / etc/ drbd. conf : 



global { usage-count no; } 
common { syncer { rate 100M; } } 
resource rO { 

protocol C; 
startup { 

wfc-timeout 15; 
degr-wf c-timeout 60; 

} 

net { 

cram-hmac-alg shal; 
shared-secret "secret"; 

} 

on drbdOl { 

device /dev/drbdO; 

disk /dev/sdbl; 

address 192.168.0.1:7788; 

meta-disk internal; 

} 

on drbd02 { 

device /dev/drbdO; 

disk /dev/sdbl; 

address 192.168.0.2:7788; 
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meta-disk internal; 

} 

} 




There are many other options in /etc/drbd.conf , but for this example their default 
values are fine. 



• Now copy /etc/drbd.conf to the second host: 

scp /etc/drbd.conf drbd02:~ 

• And, on drbd02 move the file to /etc: 

sudo mv drbd.conf /etc/ 

• Now using the drbdadm utility initialize the meta data storage. On each server execute: 

sudo drbdadm create-md rO 

• Next, on both hosts, start the drbd daemon: 

sudo service drbd start 

• On the drbdOl , or whichever host you wish to be the primary, enter the following: 

sudo drbdadm -- --overwrite-data-of-peer primary all 

• After executing the above command, the data will start syncing with the secondary host. To watch 
the progress, on drbd02 enter the following: 

watch -nl cat /proc/drbd 

To stop watching the output press Ctrl+c. 

• Finally, add a filesystem to /dev/drbdo and mount it: 

sudo mkfs.ext3 /dev/drbdO 
sudo mount /dev/drbdO /srv 

1.2. Testing 

To test that the data is actually syncing between the hosts copy some files on the drbdOl, the primary, 
to /srv: 

sudo cp -r /etc/default /srv 

Next, unmount /srv: 

sudo umount /srv 
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Demote the primary server to the secondary role: 
sudo drbdadm secondary rO 

Now on the secondary server promote it to the primary role: 

sudo drbdadm primary rO 

Lastly, mount the partition: 

sudo mount /dev/drbdO /srv 

Using Is you should see /srv/default copied from the former primary host drbdOl. 

1.3. References 

• For more information on DRBD see the DRBD web site 1 . 

• The drbd.confman page 2 contains details on the options not covered in this guide. 

• Also , see the drbdadm man page 3 . 

• The DRBD Ubuntu Wiki 4 page also has more information. 



http://www.drbd.org/ 

http://manpages.ubuntu.eom/manpages/trusty/en/man5/drbd.conf.5.html 
http://manpages.ubuntu.eom/manpages/trusty/en/man8/drbdadm.8.html 
https://help.ubuntu.com/community/DRBD 
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Chapter 23. VPN 

Open VPN is a Virtual Private Networking (VPN) solution provided in the Ubuntu Repositories. It is 
flexible, reliable and secure. It belongs to the family of SSL/TLS VPN stacks (different from IPSec 
VPNs). This chapter will cover installing and configuring Open VPN to create a VPN. 
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1. Open VPN 

If you want more than just pre-shared keys OpenVPN makes it easy to setup and use a Public Key 
Infrastructure (PKI) to use SSL/TLS certificates for authentication and key exchange between 
the VPN server and clients. OpenVPN can be used in a routed or bridged VPN mode and can be 
configured to use either UDP or TCP. The port number can be configured as well, but port 1 194 is the 
official one. And it is only using that single port for all communication. VPN client implementations 
are available for almost anything including all Linux distributions, OS X, Windows and OpenWRT 
based WLAN routers. 

1.1. Server Installation 

To install openvpn in a terminal enter: 
sudo apt-get install openvpn easy-rsa 

1.2. Public Key Infrastructure Setup 

The first step in building an OpenVPN configuration is to establish a PKI (public key infrastructure). 
The PKI consists of: 

• a separate certificate (also known as a public key) and private key for the server and each client, 
and 

• a master Certificate Authority (CA) certificate and key which is used to sign each of the server and 
client certificates. 

OpenVPN supports bidirectional authentication based on certificates, meaning that the client must 
authenticate the server certificate and the server must authenticate the client certificate before mutual 
trust is established. 

Both server and client will authenticate the other by first verifying that the presented certificate 
was signed by the master certificate authority (CA) , and then by testing information in the now- 
authenticated certificate header, such as the certificate common name or certificate type (client or 
server) . 

1.2.1. Certificate Authority Setup 

To setup your own Certificate Authority (CA) and generating certificates and keys for an OpenVPN 
server and multiple clients first copy the easy-rsa directory to /etc/openvpn. This will ensure that 
any changes to the scripts will not be lost when the package is updated. From a terminal change to 
user root and: 

mkdir /etc/openvpn/easy-rsa/ 

cp -r /usr/share/easy-rsa/* /etc/openvpn/easy-rsa/ 
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Next, edit /etc/openvpn/easy-rsa/vars adjusting the following to your environment: 



export KEY_COUNTRY="US" 
export KEY_PROVINCE="NC" 
export KEY_CITY= "Winston-Salem" 
export KEY_ORG=" Example Company" 
export KEY_EMAIL= " steve@ example . com" 
export KEY_CN=MyVPN 
export KEY_NAME=MyVPN 
export KEY_OU=MyVPN 



Enter the following to generate the master Certificate Authority (CA) certificate and key: 

cd /etc/openvpn/easy-rsa/ 
source vars 
. /clean-all 
. /build-ca 

1.2.2. Server Certificates 

Next, we will generate a certificate and private key for the server: 
./build-key-server myservername 

As in the previous step, most parameters can be defaulted. Two other queries require positive 
responses, "Sign the certificate? [y/n]" and "1 out of 1 certificate requests certified, commit? [y/n]". 

Diffie Hellman parameters must be generated for the Open VPN server: 
./build-dh 

All certificates and keys have been generated in the subdirectory keys/. Common practice is to copy 
them to /etc/openvpn/: 

cd keys/ 

cp myservername. crt myservername . key ca.crt dh2048.pem /etc/openvpn/ 

1.2.3. Client Certificates 

The VPN client will also need a certificate to authenticate itself to the server. Usually you create a 
different certificate for each client. To create the certificate, enter the following in a terminal while 
being user root: 



cd /etc/openvpn/easy-rsa/ 
source vars 
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./build-key clientl 

Copy the following files to the client using a secure method: 

• /etc/open vpn/ca.crt 

• /etc/openvpn/easy-rsa/keys/clientl .crt 

• /etc/openvpn/easy-rsa/keys/clientl .key 

As the client certificates and keys are only required on the client machine, you should remove them 
from the server. 

1.3. Simple Server Configuration 

Along with your Open VPN installation you got these sample config files (and many more if if you 
check): 

root@server : /# Is -1 /usr/share/doc/openvpn/examples/sample-conf ig-f iles/ 
total 68 

-rw-r — r — 1 root root 3427 2011-07-04 15:09 client. conf 
-rw-r — r — 1 root root 4141 2011-07-04 15:09 server .conf . gz 

Start with copying and unpacking server. conf .gz to /etc/open vpn/server .conf. 

sudo cp /usr/share/doc/openvpn/examples/sample-conf ig-f iles/server . conf . gz /etc/openvpn/ 
sudo gzip -d /etc/openvpn/server.conf .gz 

Edit /etc/openvpn/server.conf to make sure the following lines are pointing to the certificates and 
keys you created in the section above. 

ca ca.crt 

cert myservername.crt 
key myservername . key 
dh dh2048.pem 

That is the minimum you have to configure to get a working OpenVPN server. You can use all the 
default settings in the sample server .conf file. Now start the server. You will find logging and error 
messages in your syslog. 

root@server : /etc/openvpn# service openvpn start 
* Starting virtual private network daemon (s)... 

* Autostarting VPN ' server ' [ OK ] 

Now check if OpenVPN created a tunO interface: 
root@server : /etc/openvpn# if config tunO 

tunO Link encap:UNSPEC HWaddr 00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00 
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inet addr : 10 . 8 . 0 . 1 P-t-P : 10 . 8 . 0 . 2 Mask : 255 . 255 . 255 . 255 

UP POINTOPOINT RUNNING NOARP MULTICAST MTU: 1500 Metric : 1 

[ • • • ] 

1.4. Simple Client Configuration 

There are various different Open VPN client implementations with and without GUIs. You can 
read more about clients in a later section. For now we use the Open VPN client for Ubuntu which 
is the same executable as the server. So you have to install the openvpn package again on the client 
machine: 

sudo apt-get install openvpn 

This time copy the client .conf sample config file to /etc/open vpn/. 

sudo cp /usr/share/doc/openvpn/examples/sample-conf ig-f iles/client . conf /etc/openvpn/ 

Copy the client keys and the certificate of the CA you created in the section above to e.g. /etc/ 
openvpn/ and edit /etc/openvpn/ciient.conf to make sure the following lines are pointing to those 
files. If you have the files in /etc/openvpn/ you can omit the path. 

ca ca.crt 

cert clientl.crt 

key clientl.key 

And you have to at least specify the Open VPN server name or address. Make sure the keyword client 
is in the config. That's what enables client mode. 

client 

remote vpnserver.example.com 1194 

Also, make sure you specify the key file names you copied from the server 



ca ca.crt 

cert clientl.crt 

key clientl.key 

Now start the Open VPN client: 



root@client : /etc/openvpn# service openvpn start 
* Starting virtual private network daemon (s)... 

* Autostarting VPN 'client' [ OK ] 

Check if it created a tunO interface: 
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root@client : /etc/openvpn# ifconfig tunO 

tunO Link encap:UNSPEC HWaddr 00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00 

inet addr : 10 . 8 . 0 . 6 P-t-P : 10 . 8 . 0 . 5 Mask : 255 . 255 . 255 . 255 
UP POINTOPOINT RUNNING NOARP MULTICAST MTU: 1500 Metric:! 



Check if you can ping the Open VPN server: 



root@client : /etc/openvpn# ping 10.8.0.1 

PING 10.8.0.1 (10.8.0.1) 56(84) bytes of data. 

64 bytes from 10.8.0.1: icmp_req=l ttl=64 time=0.920 ms 



The OpenVPN server always uses the first usable IP address in the client network and only 
that IP is pingable. E.g. if you configured a /24 for the client network mask, the .1 address 
will be used. The P-t-P address you see in the ifconfig output above is usually not answering 
ping requests. 



Check out your routes: 



root@client : /etc/openvpn# netstat -rn 
Kernel IP routing table 
Destination Gateway 
10.8.0.5 0.0.0.0 
10.8.0.1 10.8.0.5 
192.168.42.0 0.0.0.0 
0.0.0.0 192.168.42.1 



Genmask Flags 
255.255.255.255 UH 
255.255.255.255 UGH 
255.255.255.0 U 
0.0.0.0 UG 



MSS Window 
0 0 
0 0 
0 0 
0 0 



irtt Iface 
0 tunO 
0 tunO 
0 ethO 
0 ethO 



1 .5 . First trouble shooting 



If the above didn't work for you, check this: 

• Check your syslog, e.g. grep -i vpn /var/log/syslog 

• Check that you have specified the keyfile names correctly in client.conf and server .conf. 

• Can the client connect to the server machine? Maybe a firewall is blocking access? Check syslog 
on server. 

• Client and server must use same protocol and port, e.g. UDP port 1 194, see port and proto config 
option 

• Client and server must use same config regarding compression, see comp-lzo config option 

• Client and server must use same config regarding bridged vs routed mode, see server vs server- 
bridge config option 

1 .6. Advanced configuration 

1.6.1. Advanced routed VPN configuration on server 

The above is a very simple working VPN. The client can access services on the VPN server machine 
through an encrypted tunnel. If you want to reach more servers or anything in other networks, 
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push some routes to the clients. E.g. if your company's network can be summarized to the network 
192.168.0.0/16, you could push this route to the clients. But you will also have to change the routing 
for the way back - your servers need to know a route to the VPN client-network. 

Or you might push a default gateway to all the clients to send all their internet traffic to the VPN 
gateway first and from there via the company firewall into the internet. This section shows you some 
possible options. 

Push routes to the client to allow it to reach other private subnets behind the server. Remember that 
these private subnets will also need to know to route the Open VPN client address pool (10.8.0.0/24) 
back to the Open VPN server. 

push "route 10.0.0.0 255.0.0.0" 

If enabled, this directive will configure all clients to redirect their default network gateway through 
the VPN, causing all IP traffic such as web browsing and DNS lookups to go through the VPN (the 
Open VPN server machine or your central firewall may need to NAT the TUN/TAP interface to the 
internet in order for this to work properly). 

push "redirect-gateway defl bypass-dhcp" 

Configure server mode and supply a VPN subnet for Open VPN to draw client addresses from. The 
server will take 10.8.0.1 for itself, the rest will be made available to clients. Each client will be able to 
reach the server on 10.8.0.1. Comment this line out if you are ethernet bridging. 

server 10.8.0.0 255.255.255.0 

Maintain a record of client to virtual IP address associations in this file. If Open VPN goes down or 
is restarted, reconnecting clients can be assigned the same virtual IP address from the pool that was 
previously assigned. 

if conf ig-pool-persist ipp.txt 
Push DNS servers to the client. 

push "dhcp-option DNS 10.0.0.2" 
push "dhcp-option DNS 10.1.0.2" 

Allow client to client communication. 

client-to-client 

Enable compression on the VPN link. 
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comp-lzo 

The keepalive directive causes ping-like messages to be sent back and forth over the link so that each 
side knows when the other side has gone down. Ping every 1 second, assume that remote peer is down 
if no ping received during a 3 second time period. 

keepalive 1 3 

It's a good idea to reduce the Open VPN daemon's privileges after initialization. 

user nobody 
group nogroup 

Open VPN 2.0 includes a feature that allows the OpenVPN server to securely obtain a username and 
password from a connecting client, and to use that information as a basis for authenticating the client. 
To use this authentication method, first add the auth-user-pass directive to the client configuration. It 
will direct the OpenVPN client to query the user for a username/password, passing it on to the server 
over the secure TLS channel. 

# client config! 
auth-user-pass 

This will tell the OpenVPN server to validate the username/password entered by clients using the 
login PAM module. Useful if you have centralized authentication with e.g. Kerberos. 

plugin /usr/lib/openvpn/openvpn-plugin-auth-pam. so login 
j^-j Please read the OpenVPN hardening security guide 1 for further security advice. 

1.6.2. Advanced bridged VPN configuration on server 

OpenVPN can be setup for either a routed or a bridged VPN mode. Sometimes this is also referred 
to as OSI layer-2 versus layer-3 VPN. In a bridged VPN all layer-2 frames - e.g. all ethernet frames 
- are sent to the VPN partners and in a routed VPN only layer-3 packets are sent to VPN partners. 
In bridged mode all traffic including traffic which was traditionally LAN-local like local network 
broadcasts, DHCP requests, ARP requests etc. are sent to VPN partners whereas in routed mode this 
would be filtered. 

1 .6 2 .1 . Prepare interface config for bridging on server 
Make sure you have the bridge-utils package installed: 



http://openvpn.net/index.php/open-source/documentation/howto .html#security 
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sudo apt-get install bridge-utils 

Before you setup Open VPN in bridged mode you need to change your interface configuration. Let's 
assume your server has an interface ethO connected to the internet and an interface ethl connected to 
the LAN you want to bridge. Your /etc/network/interfaces would like this: 

auto ethO 

iface ethO inet static 
address 1.2.3.4 
netmask 255.255.255.248 
default 1.2.3.1 

auto ethl 

iface ethl inet static 
address 10.0.0.4 
netmask 255.255.255.0 

This straight forward interface config needs to be changed into a bridged mode like where the config 
of interface ethl moves to the new brO interface. Plus we configure that brO should bridge interface 
ethl. We also need to make sure that interface ethl is always in promiscuous mode - this tells the 
interface to forward all ethernet frames to the IP stack. 

auto ethO 

iface ethO inet static 
address 1.2.3.4 
netmask 255.255.255.248 
default 1.2.3.1 

auto ethl 

iface ethl inet manual 

up ip link set $IFACE up promise on 

auto brO 

iface brO inet static 
address 10.0.0.4 
netmask 255.255.255.0 
bridge_ports ethl 

At this point you need to bring up the bridge. Be prepared that this might not work as expected and 
that you will lose remote connectivity. Make sure you can solve problems having local access. 

sudo ifdown ethl && sudo ifup -a 

1.6.2.2. Prepare server config for bridging 

Edit /etc/openvpn/server .conf changing the following options to: 
; dev tun 
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dev tap 

up "/etc/openvpn/up.sh brO ethl" 
;server 10.8.0.0 255.255.255.0 

server-bridge 10.0.0.4 255.255.255.0 10.0.0.128 10.0.0.254 

Next, create a helper script to add the tap interface to the bridge and to ensure that ethl is 
promiscuous mode. Create /etc/openvpn/up.sh: 

#!/bin/sh 

BR=$1 

ETHDEV=$2 

TAPDEV=$3 

/sbin/ip link set "$TAPDEV" up 
/sbin/ip link set "$ETHDEV" promise on 
/sbin/brctl addif $BR $ TAP DEV 

Then make it executable: 

sudo chmod 7 55 /etc/openvpn/up.sh 

After configuring the server, restart openvpn by entering: 

sudo service openvpn restart 

1.6.2.3. Client Configuration 
First, install openvpn on the client: 

sudo apt-get install openvpn 

Then with the server configured and the client certificates copied to the /etc/openvpn/ directory, 
create a client configuration file by copying the example. In a terminal on the client machine enter: 

sudo cp /usr/share/doc/openvpn/examples/sample-conf ig-f iles/client . conf /etc/openvpn 

Now edit /etc/openvpn/ciient.conf changing the following options: 

dev tap 

; dev tun 

ca ca.crt 

cert clientl.crt 

key clientl.key 

Finally, restart openvpn: 
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sudo service openvpn restart 

You should now be able to connect to the remote LAN through the VPN. 

1.7. Client software implementations 

1.7.1. Linux Network-Manager GUI for Open VPN 

Many Linux distributions including Ubuntu desktop variants come with Network Manager, a nice 
GUI to configure your network settings. It also can manage your VPN connections. Make sure you 
have package network- manager-openvpn installed. Here you see that the installation installs all other 
required packages as well: 

root@client : ~# apt-get install network-manager-openvpn 

Reading package lists... Done 

Building dependency tree 

Reading state information. . . Done 

The following extra packages will be installed: 

liblzo2-2 libpkcsll-helperl network-manager-openvpn-gnome openvpn 
Suggested packages: 

resolvconf 

The following NEW packages will be installed: 

liblzo2-2 libpkcsll-helperl network-manager-openvpn 

network-manager-openvpn-gnome openvpn 
0 upgraded, 5 newly installed, 0 to remove and 631 not upgraded. 
Need to get 700 kB of archives. 

After this operation, 3,031 kB of additional disk space will be used. 
Do you want to continue [Y/n]? 

To inform network-manager about the new installed packages you will have to restart it: 

rootgclient : ~# restart network-manager 
network-manager start/running, process 3078 

Open the Network Manager GUI, select the VPN tab and then the 'Add' button. Select Open VPN as 
the VPN type in the opening requester and press 'Create'. In the next window add the Open VPN's 
server name as the 'Gateway', set 'Type' to 'Certificates (TLS)', point 'User Certificate' to your user 
certificate, 'CA Certificate' to your CA certificate and 'Private Key' to your private key file. Use the 
advanced button to enable compression (e.g. comp-lzo), dev tap, or other special settings you set on 
the server. Now try to establish your VPN. 

1.7.2. Open VPN with GUI for Mac OS X: Tunnelblick 

Tunnelblick is an excellent free, open source implementation of a GUI for OpenVPN for OS X. The 
project's homepage is at http://code.google.eom/p/tunnelblick/. Download the latest OS X installer 
from there and install it. Then put your client .ovpn config file together with the certificates and keys 
in /Users/username/Library/ Application Support/Tunnelblick/Configurations/ and lauch Tunnelblick 
from your Application folder. 
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# sample client. ovpn for Tunnelblick 
client 

remote blue.example.com 

port 1194 

proto udp 

dev tun 

dev-type tun 

ns-cert-type server 

reneg-sec 86400 

auth-user-pass 

auth-nocache 

auth-retry interact 

comp-lzo yes 

verb 3 

ca ca.crt 

cert client. crt 

key client. key 

1 .7 .3 . Open VPN with GUI for Win 7 

First download and install the latest OpenVPN Windows Installer 2 . Open VPN 2.3.2 was the latest 
when this was written. As of this writing, the management GUI is included with the Windows binary 
installer. 

You need to start the OpenVPN service. Goto Start > Computer > Manage > Services and 
Applications > Services. Find the OpenVPN service and start it. Set it's startup type to automatic. 
When you start the OpenVPN MI GUI the first time you need to run it as an administrator. You have 
to right click on it and you will see that option. 

You will have to write your OpenVPN config in a textfile and place it in C:\Program FilesXOpenVPN 
\config\client.ovpn along with the CA certificate. You could put the user certificate in the user's home 
directory like in the foil wing example. 

# C:\Program Files\OpenVPN\conf ig\client . ovpn 
client 

remote server . example . com 
port 1194 
proto udp 
dev tun 
dev-type tun 
ns-cert-type server 
reneg-sec 86400 
auth-user-pass 
auth-retry interact 
comp-lzo yes 
verb 3 
ca ca.crt 



http://www.openvpn.net/index.php/open-source/downloads.html 
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cert "C : \\Users\\username\\My DocumentsWopenvpnWclient.crt" 

key "C : \\Users\\username\\My DocumentsWopenvpnWclient . key" 

management 127.0.0.1 1194 

management-hold 

management-query-passwords 

auth-retry interact 

; Set the name of the Windows TAP network interface device here 
dev-node MyTAP 

Note: If you are not using user authentication and/or you want to run the service without user 
interaction, comment out the following options: 

auth-user-pass 
auth-retry interact 
management 127.0.0.1 1194 
management-hold 
management-query-passwords 

You may want to set the Windows service to "automatic". 
1.7.4. Open VPN for QpenWRT 

OpenWRT is described as a Linux distribution for embedded devices like WLAN router. There are 
certain types of WLAN routers who can be flashed to run OpenWRT. Depending on the available 
memory on your OpenWRT router you can run software like OpenVPN and you could for example 
build a small inexpensive branch office router with VPN connectivity to the central office. More 
info on OpenVPN on OpenWRT is here 3 . And here is the OpenWRT project's homepage: http:ll 
openwrt.org 

Log into your OpenWRT router and install OpenVPN: 

opkg update 

opkg install openvpn 

Check out /etc/config/openvpn and put your client config in there. Copy certificates and keys to /etc/ 
openvpn/ 

config openvpn clientl 

option enable 1 

option client 1 
# option dev tap 



option 
option 
option 
option 



dev tun 



proto udp 

ca /etc/openvpn/ca.crt 

cert /etc/openvpn/client.crt 



http://wiki.openwrt.org/doc/howto/vpn.overview 
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option key /etc/openvpn/client.key 
option comp_lzo 1 

Restart Open VPN: 
service openvpn restart 

You will have to see if you need to adjust your router's routing and firewall rules. 

1 .8 . References 

• See the OpenVPN 1 " website for additional information. 

• OpenVPN hardening security guide 5 

• Also, Pakt's OpenVPN: Building and Integrating Virtual Private Networks 6 is a good resource. 



http://openvpn.net/ 

http://openvpn.net/index.php/open-source/documentation/howto .html#security 
http://www.packtpub.com/openvpn/book 
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Chapter 24. Other Useful Applications 

There are many very useful applications developed by the Ubuntu Server Team, and others that are 
well integrated with Ubuntu Server Edition, that might not be well known. This chapter will showcase 
some useful applications that can make administering an Ubuntu server, or many Ubuntu servers, that 
much easier. 
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l.pam motd 

When logging into an Ubuntu server you may have noticed the informative Message Of The Day 
(MOTD). This information is obtained and displayed using a couple of packages: 

• landscape-common: provides the core libraries of landscape-client, which is needed to manage 
systems with Landscape 1 (proprietary). Yet the package also includes the landscape-sysinfo utility 
which is responsible for displaying core system data involving cpu, memory, disk space, etc. For 
instance: 



System load: 0.0 Processes: 76 

Usage of / : 30.2% of 3.11GB Users logged in: 1 

Memory usage: 20% IP address for ethO : 10.153.107.115 

Swap usage: 0% 

Graph this data and manage this system at https://landscape.canonical.com/ 



You can run landscape-sysinfo manually at any time. 



• update-notifier-common: provides information on available package updates, impending filesystem 
checks (fsck), and required reboots (e.g.: after a kernel upgrade). 

pam_motd executes the scripts in /etc/update-motd.d in order based on the number prepended to 
the script. The output of the scripts is written to /var/run/motd, keeping the numerical order, then 
concatenated with /etc/motd.taii. 



You can add your own dynamic information to the MOTD. For example, to add local weather 
information: 

• First, install the weather-util package: 



sudo apt-get install weather-util 

• The weather utility uses METAR data from the National Oceanic and Atmospheric Administration 
and forecasts from the National Weather Service. In order to find local information you will need 
the 4-character ICAO location indicator. This can be determined by browsing to the National 
Weather Service 2 site. 

Although the National Weather Service is a United States government agency there are weather 
stations available world wide. However, local weather information for all locations outside the U.S. 
may not be available. 

' http://landscape .canonical.com/ 

2 

http://www.weather.gov/tg/siteloc.shtml 
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• Create /usr/iocal/bin/local-weather, a simple shell script to use weather with your local ICAO 
indicator: 

#!/bin/sh 

# 

# 

# Prints the local weather information for the MOTD. 

# 
# 

# Replace KINT with your local weather station. 

# Local stations can be found here: http://www.weather.gov/tg/siteloc.shtml 
echo 

weather -i KINT 
echo 

• Make the script executable: 

sudo chmod 755 /usr/local/bin/local-weather 

• Next, create a symlink to /etc/update-motd.d/98-local-weather: 

sudo In -s /usr/local/bin/local-weather /etc/update-motd.d/98-local-weather 

• Finally, exit the server and re-login to view the new MOTD. 

You should now be greeted with some useful information, and some information about the local 
weather that may not be quite so useful. Hopefully the local-weather example demonstrates the 
flexibility of pam_motd. 
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2. etckeeper 

etckeeper allows the contents of /etc be easily stored in Version Control System (VCS) repository. 
It hooks into apt to automatically commit changes to /etc when packages are installed or upgraded. 
Placing /etc under version control is considered an industry best practice, and the goal of etckeeper is 
to make this process as painless as possible. 

Install etckeeper by entering the following in a terminal: 



sudo apt-get install etckeeper 

The main configuration file, /etc/etckeeper/etckeeper .conf , is fairly simple. The main option is 
which VCS to use. By default etckeeper is configured to use bzr for version control. The repository is 
automatically initialized (and committed for the first time) during package installation. It is possible to 
undo this by entering the following command: 



sudo etckeeper uninit 

By default, etckeeper will commit uncommitted changes made to /etc daily. This can be disabled 
using the AVOID_DAILY_AUTOCOMMITS configuration option. It will also automatically 
commit changes before and after package installation. For a more precise tracking of changes, it is 
recommended to commit your changes manually, together with a commit message, using: 

sudo etckeeper commit "..Reason for configuration change.." 

Using the VCS commands you can view log information about files in /etc: 

sudo bzr log /etc/passwd 

To demonstrate the integration with the package management system, install postfix: 



sudo apt-get install postfix 

When the installation is finished, all the postfix configuration files should be committed to the 
repository: 



Committing to: /etc/ 
added aliases. db 
modified group 
modified group- 
modified gshadow 
modified gshadow- 
modified passwd 
modified passwd- 
added postfix 
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added resolvconf 
added rsyslog.d 
modified shadow 
modified shadow- 
added init . d/postf ix 
added network/if -down . d/postf ix 
added network/if -up . d/postf ix 
added postf ix/dynamicmaps . cf 
added postf ix/main . cf 
added postf ix/master . cf 
added postfix/post-install 
added postfix/postfix-files 
added postfix/postfix-script 
added postfix/sasl 
added ppp/ip-down.d 
added ppp/ip-down . d/postf ix 
added ppp/ip-up . d/postf ix 
added rcO . d/K20postf ix 
added rcl .d/K20postf ix 
added rc2 .d/S20postf ix 
added rc3 . d/S20postf ix 
added rc4 . d/S20postf ix 
added rc5 .d/S20postf ix 
added rc6 . d/K20postf ix 
added resolvconf /update-libc .d 
added resolvconf /update-libc . d/postf ix 
added rsyslog . d/postf ix . conf 
added uf w/applications . d/postf ix 
Committed revision 2 . 

For an example of how etckeeper tracks manual changes, add new a host to /etc/hosts. Using bzr 
you can see which files have been modified: 

sudo bzr status /etc/ 

modified : 
hosts 

Now commit the changes: 

sudo etckeeper commit "new host" 

For more information on bzr see Section 1, "Bazaar" [p. 271]. 
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3. Byobu 

One of the most useful applications for any system administrator is screen. It allows the execution of 
multiple shells in one terminal. To make some of the advanced screen features more user friendly, and 
provide some useful information about the system, the byobu package was created. 

When executing byobu pressing the F9 key will bring up the Configuration menu. This menu will 
allow you to: 

• View the Help menu 

• Change Byobu's background color 

• Change Byobu's foreground color 

• Toggle status notifications 

• Change the key binding set 

• Change the escape sequence 

• Create new windows 

• Manage the default windows 

• Byobu currently does not launch at login (toggle on) 

The key bindings determine such things as the escape sequence, new window, change window, etc. 
There are two key binding sets to choose from f-keys and screen-escape-keys . If you wish to use the 
original key bindings choose the none set. 

byobu provides a menu which displays the Ubuntu release, processor information, memory 
information, and the time and date. The effect is similar to a desktop menu. 

Using the "Byobu currently does not launch at login (toggle on)" option will cause byobu to be 
executed any time a terminal is opened. Changes made to byobu are on a per user basis, and will not 
affect other users on the system. 

One difference when using byobu is the scrollback mode. Press the F7 key to enter scrollback mode. 
Scrollback mode allows you to navigate past output using vi like commands. Here is a quick list of 
movement commands: 

• h - Move the cursor left by one character 

• j - Move the cursor down by one line 

• k - Move the cursor up by one line 

• / - Move the cursor right by one character 

• 0 - Move to the beginning of the current line 

• $ - Move to the end of the current line 

• G - Moves to the specified line (defaults to the end of the buffer) 

• / - Search forward 
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• ? - Search backward 

• n - Moves to the next match, either forward or backward 
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4. References 

• See the update-motd man page 3 for more options available to update-motd. 

• The Debian Package of the Day weather 4 article has more details about using the weatherutility. 

• See the etckeeper 5 site for more details on using etckeeper. 

• The etckeeper Ubuntu Wiki 6 page. 

• For the latest news and information about bzr see the bzr 1 web site. 

• For more information on screen see the screen web site & . 

• And the Ubuntu Wiki screen 9 page. 

• Also, see the byobu project page 10 for more information. 



http://manpages.ubuntu.com/manpages/trasty/en/man5/update-motd.5.html 

http://debaday.debian.net/2007/10/04/weather-check-weather-conditions-and-forecasts-on-the-command-line/ 

http://kitenet.net/~joey/code/etckeeper/ 

https://help.ubuntu.com/community/etckeeper 

http ://bazaar-vc s .org/ 

http://www.gnu.org/software/screen/ 

https://help.ubuntu.com/community/Screen 

3 https://launchpad.net/byobu 
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1. Reporting Bugs in Ubuntu Server Edition 

The Ubuntu Project, and thus Ubuntu Server, uses Launchpad 1 as its bugtracker. In order to file a bug, 
you will need a Launchpad account. Create one here 2 if necessary. 

1.1. Reporting Bugs With apport-cli 

The preferred way to report a bug is with the apport-cli command. It must be invoked on the machine 
affected by the bug because it collects information from the system on which it is being run and 
publishes it to the bug report on Launchpad. Getting that information to Launchpad can therefore be a 
challenge if the system is not running a desktop environment in order to use a browser (common with 
servers) or if it does not have Internet access. The steps to take in these situations are described below. 

*— I The commands apport-cli and ubuntu-bug should give the same results on a CLI server. 

The latter is actually a symlink to apport-bug which is intelligent enough to know whether a 
desktop environment is in use and will choose apport-cli if not. Since server systems tend to 
be CLI-only apport-cli was chosen from the outset in this guide. 

Bug reports in Ubuntu need to be filed against a specific software package, so the name of the 
package (source package or program name/path) affected by the bug needs to be supplied to apport- 
cli: 

apport-cli PACKAGENAME 




See Chapter 3, Package Management [p. 20] for more information about packages in 
Ubuntu. 



Once apport-cli has finished gathering information you will be asked what to do with it. For instance, 
to report a bug in vim: 

apport-cli vim 

*** Collecting problem information 

The collected information can be sent to the developers to improve the 
application. This might take a few minutes. 

*** Send problem report to the developers? 

After the problem report has been sent, please fill out the form in the 
automatically opened web browser. 

What would you like to do? Your options are: 



https ://launchpad.net/ 

https://help.launchpad.net/YourAccount/NewAccount 
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S: Send report (2.8 KB) 
V: View report 

K: Keep report file for sending later or copying to somewhere else 
I : Cancel and ignore future crashes of this program version 
C: Cancel 
Please choose (S/v/K/l/C): 

The first three options are described below: 

• Send: submits the collected information to Launchpad as part of the process of filing a new bug 
report. You will be given the opportunity to describe the bug in your own words. 

*** Uploading problem information 

The collected information is being sent to the bug tracking system. 

This might take a few minutes. 

94% 

*** To continue, you must visit the following URL: 

https : //bugs . launchpad. net/ubuntu/+source/vim/+filebug/09b2495a-e2ab-lle3-879b-68b5996a96c8? 
You can launch a browser now, or copy this URL into a browser on another computer. 

Choices : 

1 : Launch a browser now 

C: Cancel 
Please choose (1/C): 1 

The browser that will be used when choosing T will be the one known on the system as www- 
browser via the Debian alternatives sy stern . Examples of text-based browsers to install include 
links, elinks, lynx, and w3m. You can also manually point an existing browser at the given URL. 

• View: displays the collected information on the screen for review. This can be a lot of information. 
Press 'Enter' to scroll by screenful. Press 'q' to quit and return to the choice menu. 

• Keep: writes the collected information to disk. The resulting file can be later used to file the bug 
report, typically after transferring it to another Ubuntu system. 

What would you like to do? Your options are: 
S: Send report (2.8 KB) 
V: View report 

K: Keep report file for sending later or copying to somewhere else 
I: Cancel and ignore future crashes of this program version 
C: Cancel 
Please choose (S/V/K/l/C): k 

Problem report file: /tmp/apport . vim. Ipg92p02 . apport 



http://manpages.ubuntu.eom/manpages/en/man8/update-altematives.8.html 
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To report the bug, get the file onto an internet-enabled Ubuntu system and apply apport-cli to it. 
This will cause the menu to appear immediately (the information is already collected). You should 
then press 's' to send: 

apport-cli apport.vim. Ipg92p02 .apport 

To directly save a report to disk (without menus) you can do: 

apport-cli vim --save apport. vim. test. apport 

Report names should end in .apport . 

If this internet-enabled system is non-Ubuntu/Debian, apport-cli is not available so the 
bug will need to be created manually. An apport report is also not to be included as an 
attachment to a bug either so it is completely useless in this scenario. 

1.2. Reporting Application Crashes 

The software package that provides the apport-cli utility, apport, can be configured to automatically 
capture the state of a crashed application. This is enabled by default (in /etc/def auit/apport). 

After an application crashes, if enabled, apport will store a crash report under /var/crash: 

-rw-r 1 peter whoopsie 150K Jul 24 16:17 _usr_lib_x86_64-linux-gnu_libmenu-cache2_libexec_iri' 

Use the apport-cli command without arguments to process any pending crash reports. It will offer to 
report them one by one. 

apport-cli 

*** Send problem report to the developers? 

After the problem report has been sent, please fill out the form in the 
automatically opened web browser. 

What would you like to do? Your options are: 
S: Send report (153.0 KB) 
V: View report 

K: Keep report file for sending later or copying to somewhere else 
I: Cancel and ignore future crashes of this program version 
C: Cancel 
Please choose (S/V/K/I/C): s 

If you send the report, as was done above, the prompt will be returned immediately and the /var/ 
crash directory will then contain 2 extra files: 
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-rw-r 1 peter whoopsie 150K Jul 24 16:17 

-rw-rw-r — 1 peter whoopsie 0 Jul 24 16:37 
-rw 1 whoopsie whoopsie 0 Jul 24 16:37 



usr_lib_x86_64-linux-gnu_libmenu-cache2_libexec 
usr_lib_x86_64-linux-gnu_libmenu-cache2_libexec 
usr_lib_x86_64-linux-gnu_libmenu-cache2_libexec 



Sending in a crash report like this will not immediately result in the creation of a new public bug. The 
report will be made private on Launchpad, meaning that it will be visible to only a limited set of bug 
triagers. These triagers will then scan the report for possible private data before creating a public bug. 

1.3. Resources 

• See the Reporting Bugs 4 Ubuntu wiki page. 

• Also, the Apport 5 page has some useful information. Though some of it pertains to using a GUI. 



https://help.ubuntu.com/community/ReportingBugs 
https://wiki.ubuntu.com/Apport 



374 



